diff --git a/.gitignore b/.gitignore index e5d2a11..0346237 100644 --- a/.gitignore +++ b/.gitignore @@ -65,3 +65,5 @@ build-story-editor-v2-Desktop-Debug/ build-story-editor-Desktop-Debug/ docs/.vitepress/cache/ + +docs/.vitepress/dist/ diff --git a/.vscode/settings.json b/.vscode/settings.json index f729b4a..84dc12f 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -4,6 +4,13 @@ "${workspaceFolder}/story-editor", "${workspaceFolder}/story-player", "${workspaceFolder}/software" - ] + ], + "files.associations": { + "**/frontmatter.json": "jsonc", + "**/.frontmatter/config/*.json": "jsonc", + "*.css": "tailwindcss", + "pico_i2s.pio.h": "c", + "pico_i2s.h": "c" + } } \ No newline at end of file diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 878bfe6..031de9b 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -34,7 +34,7 @@ export default defineConfig({ text: 'Bundles assembly guides', collapsed: false, items: [ - { text: 'Bundles introduction', link: '/guide-intro' }, + { text: 'Introduction', link: '/guide-intro' }, { text: 'Dev kit (Raspberry Pico)', link: '/guide-devkit-pico' } ] }, @@ -58,6 +58,8 @@ export default defineConfig({ collapsed: false, items: [ { text: 'Source code architecture', link: '/dev-intro' }, + { text: 'Micro VM documentation', link: '/dev-firmware-micro-vm' }, + { text: 'Stories file format', link: '/dev-stories' }, ] } ], diff --git a/docs/dev-firmware-micro-vm.md b/docs/dev-firmware-micro-vm.md new file mode 100644 index 0000000..f721f72 --- /dev/null +++ b/docs/dev-firmware-micro-vm.md @@ -0,0 +1,81 @@ +# Micro VM + +The stories created through the official Story Editor using graphical nodes are compiled into a binary executable. This binary is then interpreted by a micro virtual machine embedded in the OpenStory firmware. + +Here is a description of that VM. + +# Registers + +| name | number | type | call-preserved | +|-------|--------|----------------------------------|-----------| +| r0-r9 | 0-9 | general-purpose | N | +| t0-t9 | 10-19 | temporary registers | Y | +| pc | 20 | program counter | Y | +| sp | 21 | stack pointer | Y | +| ra | 22 | return address | N | + + +# Instructions + +| Instruction | Encoding | Arguments (bytes) | Description | Example | +|------- |-------- |------------- |-----------| -----| +| nop | 0 | 0 | Do nothing |  | +| halt | 1 | 0 | Halt execution |  | +| syscall | 2 | 1 | System call handled by user-registered function. Machine specific. Argument is the system call number, allowing up to 256 system calls. |  `syscall 42` | +| lcons | 3 | 4 | Store an immediate value in a register. Can also store a variable address. | `lcons r0, 0xA201d800`, `lcons r2, $DataInRam` | +| mov | 4 | 2 | Copy a register in another one. | `mov r0, r2` | +| push | 5 | 1 | Push a register onto the stack. | `push r0` | +| pop | 6 | 1 | Pop the first element of the stack to a register. | `pop r7` | +| store | 7 | 3 | Copy a value from a register to a ram address located in a register with a specified size | `store @r4, r1, 2` ; Copy R1 to address of R4, 2 bytes | +| load | 8 | 3 | Copy a value from a ram address located in a register to a register, with a specific size. | `load r0, @r3, 1` ; 1 byte | +| add | 9 | 2 | sum and store in first reg. | `add r0, r2` | +| sub | 10 | 2 | subtract and store in first reg. | ` sub r0, r2` | +| mul | 11 | 2 | multiply and store in first reg . | `mul r0, r2` | +| div | 12 | 2 | divide and store in first reg. | `div r0, r2` | +| shiftl | 13 | 2 | logical shift left. | `shl r0, r1` | +| shiftr | 14 | 2 | logical shift right. | `shr r0, r1` | +| ishiftr | 15 | 2 | arithmetic shift right (for signed values). | `ishr r0, r1` | +| and | 16 | 2 | and two registers and store result in the first one. | `and r0, r1` | +| or | 17 | 2 | or two registers and store result in the first one. | `or r0, r1` | +| xor | 18 | 2 | xor two registers and store result in the first one. | `xor r0, r1` | +| not | 19 | 1 | not a register and store result. | ` not r0` | +| call | 20 | 1 | Set register RA to the next instruction and jump to subroutine, must be a label. | `call .media` | +| ret | 21 | 0 | return to the address of last callee (RA). | `ret` | +| jump | 22 | 1 | jump to address (can use label or address). | `jump .my_label` | +| jumpr | 23 | 1 | jump to address contained in a register. | `jumpr t9` | +| skipz | 24 | 1 | skip next instruction if zero. | `skipz r0` | +| skipnz | 25 | 1 | skip next instruction if not zero. | `skipnz r2` | + +# Assembler + +Basic grammar +------------------ + +Example: + +```asm +; ---------------------------- Base node Type: Transition +.mediaEntry0004: + lcons r0, $fairy + lcons r1, $la_fee_luminelle + syscall 1 + lcons r0, .mediaEntry0006 + ret +``` + + Global variables +------------------ + +Example: + +```asm +$yourLabel DC8 "a string", 5, 4, 8 ; Déclaration de constantes +$MaVar DV32 14 ; Variable en RAM : 14 emplacements de taille 32-bits +``` + +Grammar: + +| Type | First column | Second column | Third column | Next columns | +|------- |------- |-------- |------------- |-----------| +| ROM constant | label statring with dollar sign | DC + base size (8, 16, 32) | constatant value (integer or string, surrounded by double quotes) | more values, separated by a coma | +| RAM variable | label statring with dollar sign | DV + base size (8, 16, 32) | Size of the array (number of elements) | - | diff --git a/docs/dev-stories.md b/docs/dev-stories.md new file mode 100644 index 0000000..e12e057 --- /dev/null +++ b/docs/dev-stories.md @@ -0,0 +1,24 @@ +# Stories architecture + +## Story location + +The stories are located on a SD-Card flash memory. The following file system formats are supported by openStoryTeller: + +- FAT32 +- exFAT + +Connect OpenStoryTeller to your computer using a USB cable, a USB-disk will show up on your file explorer. + +## Story tree + +A typical folder organisation is showed here: + +![arch](./images/dev-sdcard-content.png) + +At the root of the SD-Card, a special index file named `index.ost` must be present. It contains the list of installed stories as well as other informations about each story. + +## Index file format + +TLV format. + + diff --git a/docs/editor-dev.md b/docs/editor-dev.md index d4b59e0..4b9c124 100644 --- a/docs/editor-dev.md +++ b/docs/editor-dev.md @@ -14,12 +14,12 @@ The source code is found in the *story-editor* sub-directory. You'll need: -- Qt6.x development files -- Inno-setup (to generate the Windows installer) +- A C++ compiler +- CMake build utility ## How to build -Open the CMakeLists.txt with your favorite IDE (ie, QtCreator) or build from the command line. +Open the CMakeLists.txt with your favorite IDE (ie, QtCreator, Visual Studio Code) or build from the command line. # Architecture diff --git a/docs/guide-devkit-pico.md b/docs/guide-devkit-pico.md index e4ba056..2e5e91c 100644 --- a/docs/guide-devkit-pico.md +++ b/docs/guide-devkit-pico.md @@ -11,7 +11,7 @@ Current status: ON DEVELOPMENT ![pico](./images/devkit-pico.jpg) -## Bill of materials +# Bill of materials Here is an example of components. - Links are examples of what to buy, price is not optimized @@ -51,7 +51,23 @@ 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 +# Pinout + +The pins usage for this bundle is indicated by the folling wirering. OST pins are indicated in dark orange on the far left and far right (other indications come from the Pico offical pin mapping). + +![pico](./images/picow-pinout_ost.png) + +# Bundle build guide + + +# Firmware flashing + + +![pico](./images/pico-uf2-ubuntu.png) + + + +# How to build from the source code ## Clone the repository diff --git a/docs/guide-intro.md b/docs/guide-intro.md index c7c505c..3fab11c 100644 --- a/docs/guide-intro.md +++ b/docs/guide-intro.md @@ -13,9 +13,14 @@ The goal of official bundles is to test the firmware on very different kind of h The price indicated is purely informative. -## Hardware architecture overview +# Hardware architecture overview -Basically, it is a portable sound device that plays sound files and sometimes displays an image. Here is the diagram : +Basically, it is a portable sound device that plays sound files and sometimes displays an image. Here is the diagram valid of a lot of different implementations: ![proto](./images/architecture.png) +# Official bundles + +The official bundles are supported by the OpenStoryTeller firmware. It is possible to build a binary image from the source or flash redeay to use images. If your hardware is not supported, it is possible to create your own bundle by starting with an official bundle very close to your hardware. + + diff --git a/docs/images/dev-sdcard-content.png b/docs/images/dev-sdcard-content.png new file mode 100644 index 0000000..26838df Binary files /dev/null and b/docs/images/dev-sdcard-content.png differ diff --git a/docs/images/pico-uf2-ubuntu.png b/docs/images/pico-uf2-ubuntu.png new file mode 100644 index 0000000..6c73504 Binary files /dev/null and b/docs/images/pico-uf2-ubuntu.png differ diff --git a/docs/images/picow-pinout_ost.png b/docs/images/picow-pinout_ost.png new file mode 100644 index 0000000..30eb435 Binary files /dev/null and b/docs/images/picow-pinout_ost.png differ diff --git a/docs/images/picow-pinout_ost.svg b/docs/images/picow-pinout_ost.svg new file mode 100644 index 0000000..7498f0b --- /dev/null +++ b/docs/images/picow-pinout_ost.svg @@ -0,0 +1,10182 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Audio DATAIO_5IO_6LCD_D_/CLCD_CSLCD_SPI_CLKLCD_SPI DATALCD_RESETLCD_BACK_LIGHTIO_4IO_2IO_1 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Audio SCLKSD_CSSD_SPI_CLKSD_SPI_MOSIROT_1 (CLK)ROT_2 (DT)DBG _TXIO_3KEY0KEY3KEY2SD_SPI_MISOAudio LRCKROT_BUTTON diff --git a/docs/intro-getting-started.md b/docs/intro-getting-started.md index ccc3d16..1668dd7 100644 --- a/docs/intro-getting-started.md +++ b/docs/intro-getting-started.md @@ -16,10 +16,8 @@ You can help in various ways: - Report bugs on Github (open an new issue) - Propose patches, ideas, mechanical drawings, ports (open an issue) - Translate stuff -- Donate through the Itch.io page - - +Reach me on Discord: [Discord](https://monurl.ca/DiscordLuniiYT) ## Where to start @@ -67,6 +65,6 @@ Not yet, waiting for the availability of the first complete kit to determine the MIT License -Copyright (c) 2023 Anthony Rabine +Copyright (c) 2023-present Anthony Rabine diff --git a/software/library/audio_player.cpp b/software/common/audio_player.cpp similarity index 100% rename from software/library/audio_player.cpp rename to software/common/audio_player.cpp diff --git a/software/library/audio_player.h b/software/common/audio_player.h similarity index 100% rename from software/library/audio_player.h rename to software/common/audio_player.h diff --git a/software/platform/raspberry-pico-w/pico_hal_wrapper.c b/software/platform/raspberry-pico-w/pico_hal_wrapper.c index b5ba33d..20f2fb7 100644 --- a/software/platform/raspberry-pico-w/pico_hal_wrapper.c +++ b/software/platform/raspberry-pico-w/pico_hal_wrapper.c @@ -50,7 +50,7 @@ const uint8_t SD_CARD_PRESENCE = 24; #define UART_ID uart0 #define BAUD_RATE 115200 -#define UART_RX_PIN 1 +#define UART_TX_PIN 1 // PICO alarm (RTOS uses Alarm 0 and IRQ 0) #define ALARM_NUM 1 @@ -188,12 +188,12 @@ void ost_system_initialize() set_sys_clock_khz(125000, true); ////------------------- Init DEBUG LED - gpio_init(LED_PIN); - gpio_set_dir(LED_PIN, GPIO_OUT); + // gpio_init(LED_PIN); + // gpio_set_dir(LED_PIN, GPIO_OUT); //------------------- Init DEBUG PIN - gpio_init(DEBUG_PIN); - gpio_set_dir(DEBUG_PIN, GPIO_OUT); + // gpio_init(DEBUG_PIN); + // gpio_set_dir(DEBUG_PIN, GPIO_OUT); //------------------- Init UART @@ -203,7 +203,7 @@ void ost_system_initialize() // Set the TX and RX pins by using the function select on the GPIO // Set datasheet for more information on function select gpio_set_function(UART_TX_PIN, GPIO_FUNC_UART); - gpio_set_function(UART_RX_PIN, GPIO_FUNC_UART); + //------------------- Init LCD @@ -316,10 +316,10 @@ void ost_hal_gpio_set(ost_hal_gpio_t gpio, int value) switch (gpio) { case OST_GPIO_DEBUG_LED: - gpio_put(LED_PIN, value); + break; case OST_GPIO_DEBUG_PIN: - gpio_put(DEBUG_PIN, value); + break; default: break;