diff --git a/README.md b/README.md index 46f683d..89f143e 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ Open Story Teller is an Open Source project to provide guidelines and software t The main goal is to *not* make electronics boards but instead buy or reuse existing ones. This will allow you to easily repair your device with spare parts. -We propose a set of parts and firmware that is working well togather but your are free to custom everything to fit your needs. +We propose a set of parts and firmware that is working well together but your are free to custom everything to fit your needs. This project can be used as a base platform for any device that is composed by: - A display (TFT...) @@ -14,15 +14,33 @@ This project can be used as a base platform for any device that is composed by: # Links -- http://openstoryteller.org/: main documentation and project news +- http://openstoryteller.org/: main documentation, project news, guidelines, hardware shoping list... - http://github.com/arabine/open-story-teller: source code, tickets, help +# Hardware parts + +We propose the concept of bundles: a set of electronic boards that you can purchase quite easily (eg: Arduino, SeedStudio, Pimoroni, Adafruit, SparkFun...). The bundles are built around a central main board, the CPU, which comes with more or less peripherals (SD-Card reader, Wifi...). + +Several bundles will be officially supported ; this is needed for us to ensure the portability of the firmware hardware interface layer. + +Current bundles: +- Raspberry Pico (official DevKit) (ARM Cortex M0+) +- RISC-V based board (GD32VF103) + +We plan to propose a mechanical enclosure ready to be printed for an official bundle. + +See the documentation! + # Generic player software The base software is highly portable and includes a micro virtual machine. This allow potential complex stories with loops, branches, user choices, randomization... This project propose an minimal cross-platform GUI player application that can be used as a base project. +Current status: +- Project broken, needs rework to embed the micro-VM +- Qt/QML based, easily portable + # StoryTeller Editor We propose a basic editor tool to create your own stories. The generated story script runs on our micro virtual machine and allow generate complex stories. diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 234ebe0..1e6257c 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -8,7 +8,7 @@ export default defineConfig({ // https://vitepress.dev/reference/default-theme-config nav: [ { text: 'Home', link: '/' }, - { text: 'Examples', link: '/markdown-examples' } + { text: 'Documentation', link: '/intro-getting-started' } ], search: { @@ -17,10 +17,41 @@ export default defineConfig({ sidebar: [ { - text: 'Examples', + text: 'Introduction', + collapsed: false, items: [ - { text: 'Markdown Examples', link: '/markdown-examples' }, - { text: 'Runtime API Examples', link: '/api-examples' } + { text: 'Getting started', link: '/intro-getting-started' } + ] + }, + { + text: 'Bundles assembly guides', + collapsed: false, + items: [ + { text: 'Bundles introduction', link: '/guide-intro' }, + { text: 'Dev kit (Raspberry Pico)', link: '/guide-devkit-pico' }, + { text: 'SeeedStudio Wio Lite', link: '/guide-wio-lite' }, + { text: 'Arduino MKR Zero', link: '/guide-mkr-zero' } + ] + }, + { + text: 'Software player', + collapsed: false, + items: [ + { text: 'Player information', link: '/player-intro' } + ] + }, + { + text: 'Story editor', + collapsed: false, + items: [ + { text: 'User manual', link: '/editor-intro' }, + ] + }, + { + text: 'Developers corner', + collapsed: false, + items: [ + { text: 'Source code architecture', link: '/dev-intro' }, ] } ], diff --git a/docs/api-examples.md b/docs/api-examples.md deleted file mode 100644 index 6bd8bb5..0000000 --- a/docs/api-examples.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -outline: deep ---- - -# Runtime API Examples - -This page demonstrates usage of some of the runtime APIs provided by VitePress. - -The main `useData()` API can be used to access site, theme, and page data for the current page. It works in both `.md` and `.vue` files: - -```md - - -## Results - -### Theme Data -
{{ theme }}
- -### Page Data -
{{ page }}
- -### Page Frontmatter -
{{ frontmatter }}
-``` - - - -## Results - -### Theme Data -
{{ theme }}
- -### Page Data -
{{ page }}
- -### Page Frontmatter -
{{ frontmatter }}
- -## More - -Check out the documentation for the [full list of runtime APIs](https://vitepress.dev/reference/runtime-api#usedata). diff --git a/docs/dev-intro.md b/docs/dev-intro.md new file mode 100644 index 0000000..ecf66f4 --- /dev/null +++ b/docs/dev-intro.md @@ -0,0 +1,49 @@ +# Software development + +## Firmware/software + +The firmware is highly configurable and highly portable. To achieve that, it is split in multiple parts: +- The core source file, which is common to every target +- the ports, dedicated to an embedded MCU and board +- The tests, to easily test part of source on a standard PC +- A desktop/mobile implementation + +The core is written in pure C, targets implementations may add other languages and libraries (QML/C++/python ...). + + +## CMake build system + +The project uses CMake as build system. For the embedded targets, the main CMakeLists.txt includes a generic cross compiler file that should be good for many configurations as soon as your compiler is GCC. + +## Invocation + +1. Create a build directory (mkdir build) +2. Invoke cmake with some options, passed as definitions for CMake (-Doption) + +| Option | Role | +| -------------------- | --------------------------------------------------------- | +| TOOLCHAIN | specify the prefix name of the cross GCC binary | +| CMAKE_TOOLCHAIN_FILE | Includes before everything else a compiler toolchain file | +| CMAKE_BUILD_TYPE | Debug or Release (default ?) | +| OST_BUNDLE | Specify the bundle name to build | +| TOOLCHAIN_DIR | Specify a directory for the cross-gcc toolchain location | + + +Example: `cmake -DTOOLCHAIN=riscv64-unknown-elf -DCMAKE_TOOLCHAIN_FILE=cmake/cross-gcc.cmake -DCMAKE_BUILD_TYPE=Debug -DOST_BUNDLE=LONGAN_NANO ..` + + + + + + + + + + + + + + + + + diff --git a/docs/editor-intro.md b/docs/editor-intro.md new file mode 100644 index 0000000..dcaab87 --- /dev/null +++ b/docs/editor-intro.md @@ -0,0 +1,5 @@ +--- +outline: deep +--- + +# Story editor diff --git a/docs/guide-devkit-pico.md b/docs/guide-devkit-pico.md new file mode 100644 index 0000000..aaaeea6 --- /dev/null +++ b/docs/guide-devkit-pico.md @@ -0,0 +1,72 @@ +# Development kit: Raspberry Pico + +This is the official development kit. It offers the following advantages: +1. Low cost +2. Parts are easy to find +3. Low wiring/soldering: usage of a motherboard +4. SWD debug port + +Current status: ON DEVELOPMENT + +![pico](./images/devkit-pico.jpg) + + +## Bill of materials + +The minimal list of components are: + +| Part | Price | Shop | +| ----------------------------------------- | -------- | --------- | +| Audio board + speaker | 13 € | Waveshare | +| Raspberry Pico W | 9 € | Kubii | +| 2inch LCD (320x240) | 14 € | Waveshare | +| Some Pimoroni buttons are rotary switches | 4 € | Pimoroni | +| UPS module or Pimoroni LiPo Shim | 15 € | Waveshare | +| LiPo battery 500mAh | 9 € | Any | +| Carte d'extension GPIO Pico Decker | 15 € | Waveshare | +| **TOTAL** | **67 €** | + +In addition to this list, you may need some more materials such as wires, prototype boards, resistors... + +We may propose in the future a PCB to help the connection without soldering. + +![pico](./images/prototype-board.png) + + +# Developers: how to build from the source code + +## Install build tools + +Install build tools, example for a Debian based operating system: + +- sudo apt install gcc-arm-none-eabi +- sudo apt install picolibc-arm-none-eabi + +Download the pico SDK somewhere on your disk: + +``` +git clone https://github.com/raspberrypi/pico-sdk +``` + + + +Copy past the following command line, execute at the directory root. Replace the PICO_SDK_PATH value with the real location on your disk where you have installed the Pico SDK. + +First, create a CMake build directory: + +``` +mkdir build +cd build +``` +Then generate the makefile (we use the Pico toolchain here, so there is no specific toolchain file to setup.) + +``` +cmake -DCMAKE_BUILD_TYPE=Debug -DOST_BUNDLE=RASPI_PICO -DPICO_SDK_PATH=../pico-sdk -DPICO_BOARD=pico_w .. +``` + +This assume that the Pico SDK is located on the git project root directory. Change this path according to your real Pico SDK location. + + + + + diff --git a/docs/guide-intro.md b/docs/guide-intro.md new file mode 100644 index 0000000..c7c505c --- /dev/null +++ b/docs/guide-intro.md @@ -0,0 +1,21 @@ +--- +outline: deep +--- + + +# Hardware bundles + +A bundle is a collection of electronics boards that are supported by official firmware builds. They are tested and a pre-build binary is availbale to direct download. + +Keep in mind that the official bundles proposed are not "cost-optimized" or sometimes difficult to buy. There are many rooms of improvements. + +The goal of official bundles is to test the firmware on very different kind of hardware to make sure that the core firmware is highly portable. + +The price indicated is purely informative. + +## Hardware architecture overview + +Basically, it is a portable sound device that plays sound files and sometimes displays an image. Here is the diagram : + +![proto](./images/architecture.png) + diff --git a/docs/guide-mkr-zero.md b/docs/guide-mkr-zero.md new file mode 100644 index 0000000..768da0e --- /dev/null +++ b/docs/guide-mkr-zero.md @@ -0,0 +1,21 @@ +## Arduino MKR Zero (SAMD21G18A) + +| Category | Maker | Name | Rounded Price | +| ------------------ | ------------------------------ | --------------------- | ------------- | +| Main CPU board | Arduino | MKR Zero | 30€ | +| Audio | | | 15€ | +| Memory storage | Included SD card slot on board | | - | +| Battery management | Included LiPo charger on board | | - | +| Display | NewHaven 2.4" TFT | NHD-2.4-240320CF-BSXV | 22€ | + +### How to build + +Install on Ubuntu : +- sudo apt install gcc-arm-none-eabi +- sudo apt install picolibc-arm-none-eabi + +cmake -DTOOLCHAIN=arm-none-eabi -DCMAKE_TOOLCHAIN_FILE=cmake/cross-gcc.cmake -DCMAKE_BUILD_TYPE=Debug -DOST_BUNDLE=MKR_ZERO .. + +### Wiring + +TBD \ No newline at end of file diff --git a/docs/guide-wio-lite.md b/docs/guide-wio-lite.md new file mode 100644 index 0000000..e4b82f1 --- /dev/null +++ b/docs/guide-wio-lite.md @@ -0,0 +1,72 @@ +## Sipeed Longan Nano (GD32VF103CBT6) - TO BE REPLACED WITH WIO LITE + +Current status: ON DEVELOPMENT + +## What does it look like + +The firmware is still under construction. Everything is tested on breadboard. + +![proto](images/ost-1/complete.png) + +What is working: +- The audio path +- The SD Card +- Roughly: playing a wav file from the SD Card + +## Audio path + +An I2S DAC controller with a jack output : + +![proto](images/ost-1/audio_board.webp) + +An audio amplifier from Adafruit (2.5W, can drive a speaker between 3 ohms and 8 ohms). + +![proto](images/ost-1/audio_amplifier.png) + +A speaker : + +![proto](images/ost-1/speaker_4ohms_3w.png) + + + +| Category | Maker | Name | Rounded Price | +| ------------------ | ------------------------------------ | ----------- | ------------- | +| Main CPU board | Sipeed | Longan Nano | 4€ | +| Audio | | | 15€ | +| Memory storage | Included SD card slot in Longan Nano | | - | +| Battery management | | | 15€ | + + +| Part | Price | Shop | +| ------------------------------------------------- | -------- | ---------- | +| PCM5102 Audio board | 4 € | Aliexpress | +| PAM8302 Mono Amplifier | 9 € | Adafruit | +| Longan Nano RISC-V board with SD-Card port | 4 € | Aliexpress | +| 3.2" SPI TFT Screen (320x240) with ILI9341 driver | 9 € | Aliexpress | +| Adafruit PowerBoost 500 charger | 15 € | Adafruit | +| Some Pimoroni buttons are rotary switches | 4 € | Pimoroni | +| Speaker | 4 € | Pimoroni | +| LiPo battery 500mAh | 9 € | Any | +| **TOTAL** | **58 €** | + + + +### How to build + +Tools for a Debian based distro + +- sudo apt install crossbuild-essential-riscv64 +- sudo apt install picolibc-riscv64-unknown-elf + +mkdir build +cd build +cmake -DTOOLCHAIN=riscv64-unknown-elf -DCMAKE_TOOLCHAIN_FILE=cmake/cross-gcc.cmake -DCMAKE_BUILD_TYPE=Debug -DOST_BUNDLE=LONGAN_NANO .. + +Convert tools: + +- riscv64-unknown-elf-objcopy -O binary your-file.elf your-file.hex +- riscv64-unknown-elf-objcopy -O ihex your-file.elf your-file.hex + +### Wiring + +TBD diff --git a/images/architecture.png b/docs/images/architecture.png similarity index 100% rename from images/architecture.png rename to docs/images/architecture.png diff --git a/docs/images/devkit-pico.jpg b/docs/images/devkit-pico.jpg new file mode 100644 index 0000000..893dbd1 Binary files /dev/null and b/docs/images/devkit-pico.jpg differ diff --git a/docs/images/prototype-board.png b/docs/images/prototype-board.png new file mode 100644 index 0000000..e4facf7 Binary files /dev/null and b/docs/images/prototype-board.png differ diff --git a/docs/index.md b/docs/index.md index e63fe30..40bb5de 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,256 +4,24 @@ layout: home hero: name: "Open Story Teller" - text: "Make your own device that tells stories" - tagline: My great project tagline + text: "Hardware and software that tell stories" + tagline: Make your own, its free sofware actions: - theme: brand - text: Markdown Examples - link: /markdown-examples + text: Getting started + link: /intro-getting-started - theme: alt - text: API Examples - link: /api-examples + text: Assembly guidelines + link: /guide-intro features: - - title: Feature A - details: Lorem ipsum dolor sit amet, consectetur adipiscing elit - - title: Feature B - details: Lorem ipsum dolor sit amet, consectetur adipiscing elit - - title: Feature C - details: Lorem ipsum dolor sit amet, consectetur adipiscing elit + - title: Easy to repair + details: Complete information is available to change parts and explain how it works + - title: Easy to custom + details: Hardware abstraction layer to help you porting to any hardware + - title: Listen everywhere + details: Keep your stories for life, listen to any device (custom, desktop, mobile, command line...) + - title: Create complex stories + details: The story editor uses a node graph engine with programming nodes --- - -# Firmware/software - -The firmware is highly configurable and highly portable. To achieve that, it is split in multiple parts: -- The core source file, which is common to every target -- the ports, dedicated to an embedded MCU and board -- The tests, to easily test part of source on a standard PC -- A desktop/mobile implementation - -The core is written in pure C, targets implementations may add other languages and libraries (QML/C++/python ...). - -## GCC build system - -The project uses CMake as build system. For the embedded targets, the main CMakeLists.txt includes a generic cross compiler file that should be good for many configurations as soon as your compiler is GCC. - -## Invocation - -1. Create a build directory (mkdir build) -2. Invoke cmake with some options, passed as definitions for CMake (-D