More docs, fix CMake build, add VSCode config files

.gitignore

@@ -40,3 +40,7 @@ build-story-player-Desktop_Qt_6_5_1_GCC_64bit-Debug/
 build-story-player-Desktop_Qt_GCC_64bit-Debug/
 
 *.user
+
+software/build/
+
+software/.vscode/.cortex-debug.registers.state.json

docs/dev-intro.md

@@ -1,21 +1,30 @@
 # Software development
 
-## Firmware/software
+## Shared files
 
 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 core source files, which are common to every target, especially the Virtual Machine
 - 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 ...).
 
+## Software projects
 
-## CMake build system
+- The Story Editor project is located in `story-editor` directory, it is programmed in C++ and uses the Qt library
+- The multi-platform software player is located in `story-player`, it is programmed in C and uses the Raylib library
+## Firmware project
+
+Only one CMakeLists.txt project file is used to build all the official bundles.
+
+# Firmware 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
+The CMake file is located in `software` directory.
+
+## Command line invocation
 
 1. Create a build directory (mkdir build)
 2. Invoke cmake with some options, passed as definitions for CMake (-Doption)
@@ -31,19 +40,28 @@ The project uses CMake as build system. For the embedded targets, the main CMake
 
 Example: `cmake -DTOOLCHAIN=riscv64-unknown-elf -DCMAKE_TOOLCHAIN_FILE=cmake/cross-gcc.cmake  -DCMAKE_BUILD_TYPE=Debug -DOST_BUNDLE=LONGAN_NANO ..`
 
+The most important option is OST_BUNDLE which defines the hardware target.
 
+## IDE Developement
 
+You can use any C++ editor you want but we provide a ready to use and debug configuration for Visual Studio Code.
 
+Recommanded plugins are:
+- Microsoft C/C++ Extension Pack
+- Microsoft CMake tools
+- Cortex-Debug
 
+With VSCode, open the directory `software` as root of your tree view.
 
+![vscode](./images/vscode.png)
 
+1. We provide a ready to use JTAG probe configurations in the launch.json file
+2. Debug with the tool at the top
+3. Build shortcut!
+4. CMakeLists.txt must be located at the root of your tree view.
 
+## Debugging
 
-
+To debug embedded targets, we usually connect a hardware probe between the computer and the processor. We suggest to use the following probes which are supported by our scripts:
-
+- Segger JLink (great performance) for ARM and RISC-V cores
-
+- Black-Magic Probe (embeds a GDB server, native debugging with GDB)
-
-
-
-
-

docs/editor-dev.md

@@ -21,7 +21,9 @@ You'll need:
 
 Open the CMakeLists.txt with your favorite IDE (ie, QtCreator) or build from the command line.
 
-
+# Architecture
+
+![arch](story-editor-architecture.png)
 
 
 

docs/intro-getting-started.md

@@ -2,12 +2,6 @@
 
 This documentation will guide you to make your own story teller. You can choose between a purely software version (for deskto, mobile or command line), or a hardware version with electronics boards, wires and mechanical enclosure.
 
-## Project status
-
-- Story Editor is available in demo version
-- Firmware: we are focused to deliver a first version based on the Raspery Pico
-- Soft Player: available soon
-
 ## Links
 
 Before starting, here is a complete list of links where you'll find project information:

software/.vscode/c_cpp_properties.json

@@ -0,0 +1,16 @@
+{
+    "configurations": [
+        {
+            "name": "Linux",
+            "includePath": [
+                "${workspaceFolder}/**"
+            ],
+            "defines": [],
+            "compilerPath": "/usr/bin/clang",
+            "cStandard": "c17",
+            "cppStandard": "c++14",
+            "intelliSenseMode": "linux-clang-x64"
+        }
+    ],
+    "version": 4
+}

software/.vscode/launch.json

@@ -0,0 +1,45 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Cortex Debug J-Link",
+            "cwd": "${workspaceRoot}",
+            "executable": "./sketch_oct14a/build/arduino.samd.mkrzero/sketch_oct14a.ino.elf",
+            "serverpath": "/opt/SEGGER/JLink/JLinkGDBServerCLExe",
+            "request": "launch",
+            "type": "cortex-debug",
+            "servertype": "jlink",
+            "device": "ATSAMD21G18A",
+            "interface": "swd",
+            "runToMain": true,
+            "armToolchainPath": "/opt/gcc-arm-none-eabi-2020/bin/"
+        },
+        {
+            "name": "Black Magic Probe",
+            "cwd": "${workspaceRoot}",
+            "executable": "${workspaceRoot}/build/RaspberryPico/open-story-teller.elf",
+            "request": "launch",
+            "type": "cortex-debug",
+            "BMPGDBSerialPort": "/dev/ttyACM0",
+            "servertype": "bmp",
+            "interface": "swd",
+            "gdbPath": "gdb-multiarch",
+            // "device": "STM32L431VC",
+            "runToMain": true,
+            "preRestartCommands": [
+                "cd ${workspaceRoot}/build",
+                "file open-story-teller.elf",
+                // "target extended-remote /dev/ttyACM0",
+                "set mem inaccessible-by-default off",
+                "enable breakpoint",
+                "monitor reset",
+                "monitor swdp_scan",
+                "attach 1",
+                "load"
+            ]
+        }
+    ]
+}

software/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools"
+}

software/CMakeLists.txt

@@ -4,38 +4,46 @@
 # Default target: TBD ?
 # ==================================================================================================
 
-cmake_minimum_required(VERSION 3.12)
+cmake_minimum_required(VERSION 3.13)
 
 set(CMAKE_VERBOSE_MAKEFILE ON)
 set(CMAKE_COLOR_MAKEFILE ON)
 set(PROJECT_NAME open-story-teller)
 
 # ==================================================================================================
-# BUILD TYPE
+# DEFAULT VARIABLES OPTIONS
 # ==================================================================================================
+if(NOT OST_BUNDLE)
+    set(OST_BUNDLE "RASPI_PICO")
+endif()
+
+if(NOT PICO_SDK_PATH)
+    set(PICO_SDK_PATH "../pico-sdk")
+endif()
+
 if(NOT CMAKE_BUILD_TYPE)
     set(CMAKE_BUILD_TYPE Release)
-endif(NOT CMAKE_BUILD_TYPE)
+endif()
 
 # ==================================================================================================
 # OST COMMON FILES
 # ==================================================================================================
 set(OST_SRCS
-    src/main.c
+    system/main.c
-    src/sdcard.c
+    system/sdcard.c
-    src/debug.c
+    system/debug.c
-    src/picture.c
+    system/picture.c
-    src/filesystem.c
+    system/filesystem.c
-    src/ost_tasker.c
+    system/ost_tasker.c
-    src/ff/ff.c
+    system/ff/ff.c
-    src/ff/ffsystem.c
+    system/ff/ffsystem.c
-    src/ff/ff_stubs.c
+    system/ff/ff_stubs.c
 )
 include_directories(
     ${CMAKE_CURRENT_SOURCE_DIR}/include
     ${CMAKE_CURRENT_SOURCE_DIR}/library
-    ${CMAKE_CURRENT_SOURCE_DIR}/src
+    ${CMAKE_CURRENT_SOURCE_DIR}/system
-    ${CMAKE_CURRENT_SOURCE_DIR}/src/ff
+    ${CMAKE_CURRENT_SOURCE_DIR}/system/ff
 )
 
 # ==================================================================================================
@@ -130,3 +138,17 @@ elseif(${OST_BUNDLE} STREQUAL "RASPI_PICO")
 else()
     message("============= DEFAULT TARGET: LINUX CONSOLE ============= ")
 endif()
+
+# ==================================================================================================
+# CUSTOM TARGETS
+# ==================================================================================================
+add_custom_target(RaspberryPico
+    COMMAND ${CMAKE_COMMAND}
+    -DOST_BUNDLE=RASPI_PICO
+    -DPICO_SDK_PATH=../pico-sdk
+    -DPICO_BOARD=pico_w
+    -DCMAKE_BUILD_TYPE=Debug
+    -B "${CMAKE_CURRENT_BINARY_DIR}/RaspberryPico"
+    -S "${CMAKE_SOURCE_DIR}"
+    COMMAND ${CMAKE_COMMAND} --build "${CMAKE_CURRENT_BINARY_DIR}/RaspberryPico"
+)