Fix firmware build, more docs

.gitignore

@@ -65,3 +65,5 @@ build-story-editor-v2-Desktop-Debug/
 build-story-editor-Desktop-Debug/
 
 docs/.vitepress/cache/
+
+docs/.vitepress/dist/

.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"
+    }
 
 }

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' },
         ]
       }
     ],

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)   | -  |

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.
+
+

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
 

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
 

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.
+
+

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
-
-<iframe frameborder="0" src="https://itch.io/embed/2082659" width="552" height="167"><a href="https://d8s-apps.itch.io/open-story-teller">Open Story Teller by D8S Apps</a></iframe>
 
+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
 
 

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;