sprig HAL (hackclub#2450)

* sprig HAL (todo: detect presence of eeprom)

* Update HAL.c

* add comments

* commentery

firmware/sprig_hal/CMakeLists.txt

@@ -0,0 +1,45 @@
+cmake_minimum_required(VERSION 3.28)
+project(sprig_hal C CXX ASM)
+
+set(CMAKE_C_STANDARD 11)
+
+if (NOT PICO_SDK_PATH)
+    set(PICO_SDK_PATH "~/raspberrypi/pico-sdk")
+endif ()
+
+if (NOT PICO_EXTRAS_PATH)
+    set(PICO_EXTRAS_PATH "~/raspberrypi/pico-extras")
+endif ()
+
+include(pico_sdk_import.cmake)
+include(pico_extras_import.cmake)
+
+pico_sdk_init()
+add_definitions(-DPICO_NO_BI_PROGRAM_BUILD_DATE) # don't add build date into the build
+
+add_library(sprig_hal STATIC src/HAL.c)
+
+# expose stuff in /include but don't expose stuff in /src
+target_include_directories(sprig_hal PUBLIC ${PROJECT_SOURCE_DIR}/include)
+target_include_directories(sprig_hal PRIVATE ${PROJECT_SOURCE_DIR}/src)
+
+target_compile_definitions(sprig_hal PUBLIC
+        # compile time configuration of I2S
+        PICO_AUDIO_I2S_MONO_INPUT=1
+
+        PICO_AUDIO_I2S_DATA_PIN=9
+        PICO_AUDIO_I2S_CLOCK_PIN_BASE=10
+)
+
+target_link_libraries(sprig_hal PUBLIC
+        pico_stdlib
+        pico_audio_i2s
+        pico_multicore
+        hardware_spi
+        hardware_timer
+        hardware_pwm
+        hardware_adc
+)
+
+pico_enable_stdio_usb(sprig_hal 1)
+pico_enable_stdio_uart(sprig_hal 0)

firmware/sprig_hal/include/HAL.h

@@ -0,0 +1,82 @@
+#ifndef SPRIG_HAL_HAL_H
+#define SPRIG_HAL_HAL_H
+
+#include <pico/audio.h>
+#include "pico/stdlib.h"
+
+typedef struct {
+    unsigned int has_screen : 1;
+    unsigned int has_speaker : 1;
+
+    unsigned int has_button_wsad : 1;
+    unsigned int has_buttons_ijkl : 1;
+
+    unsigned int has_led_l : 1;
+    unsigned int has_led_r: 1;
+} Sprig_Features;
+
+typedef enum {
+    Button_W,
+    Button_S,
+    Button_A,
+    Button_D,
+    Button_I,
+    Button_K,
+    Button_J,
+    Button_L,
+    Button_None
+} Sprig_Button;
+
+typedef struct {
+    uint16_t hw_rev;         // 2 byte hw rev – MSB should be 1 for unofficial revs?
+    uint64_t flash_time[10]; // seconds since epoch that board was flashed
+    char pcb_color;          // might be fun – represented as a spade color character?
+    char serial[11];         // serial number (ex: BN1-034)
+    char description[32];    // human-readable free-text about the board?
+} Sprig_Data;
+
+/** Initialize hardware features */
+void hw_init();
+
+/** Get a struct of which features you have access to */
+Sprig_Features get_features();
+
+/** Get metadata about the Sprig device */
+Sprig_Data get_sprig_data();
+
+/** Get the status (0 if not pressed, non-zero if pressed) of a button */
+int get_button(Sprig_Button button);
+
+/**
+ * Set power level for left white LED
+ * @param level led level from [0, 65535]
+ */
+void set_led_l(uint16_t level);
+
+/**
+ * Set power level for left white LED
+ * @param level led level from [0, 65535]
+ */
+void set_led_r(uint16_t level);
+
+typedef uint16_t Color;
+
+/**
+ * Write a pixel to the screen- position is sequential, row-by-row then column-by-column
+ * @param color 16bit 5-6-5 RGB color
+ */
+void write_pixel(Color color);
+
+/** Start writing pixels to the screen from beginning */
+void fill_start();
+
+/** Complete writing pixels to screen */
+void fill_end();
+
+/** Get a free audio buffer to write to. When there are no buffers, returns NULL if block=false and blocks if block=true */
+struct audio_buffer *get_audio_buffer(bool block);
+
+/** Add an audio buffer back into the buffer pool to be played in reverse order of adding */
+void push_audio_buffer(audio_buffer_t *buffer);
+
+#endif //SPRIG_HAL_HAL_H

firmware/sprig_hal/pico_extras_import.cmake

@@ -0,0 +1,62 @@
+# This is a copy of <PICO_EXTRAS_PATH>/external/pico_extras_import.cmake
+
+# This can be dropped into an external project to help locate pico-extras
+# It should be include()ed prior to project()
+
+if (DEFINED ENV{PICO_EXTRAS_PATH} AND (NOT PICO_EXTRAS_PATH))
+    set(PICO_EXTRAS_PATH $ENV{PICO_EXTRAS_PATH})
+    message("Using PICO_EXTRAS_PATH from environment ('${PICO_EXTRAS_PATH}')")
+endif ()
+
+if (DEFINED ENV{PICO_EXTRAS_FETCH_FROM_GIT} AND (NOT PICO_EXTRAS_FETCH_FROM_GIT))
+    set(PICO_EXTRAS_FETCH_FROM_GIT $ENV{PICO_EXTRAS_FETCH_FROM_GIT})
+    message("Using PICO_EXTRAS_FETCH_FROM_GIT from environment ('${PICO_EXTRAS_FETCH_FROM_GIT}')")
+endif ()
+
+if (DEFINED ENV{PICO_EXTRAS_FETCH_FROM_GIT_PATH} AND (NOT PICO_EXTRAS_FETCH_FROM_GIT_PATH))
+    set(PICO_EXTRAS_FETCH_FROM_GIT_PATH $ENV{PICO_EXTRAS_FETCH_FROM_GIT_PATH})
+    message("Using PICO_EXTRAS_FETCH_FROM_GIT_PATH from environment ('${PICO_EXTRAS_FETCH_FROM_GIT_PATH}')")
+endif ()
+
+if (NOT PICO_EXTRAS_PATH)
+    if (PICO_EXTRAS_FETCH_FROM_GIT)
+        include(FetchContent)
+        set(FETCHCONTENT_BASE_DIR_SAVE ${FETCHCONTENT_BASE_DIR})
+        if (PICO_EXTRAS_FETCH_FROM_GIT_PATH)
+            get_filename_component(FETCHCONTENT_BASE_DIR "${PICO_EXTRAS_FETCH_FROM_GIT_PATH}" REALPATH BASE_DIR "${CMAKE_SOURCE_DIR}")
+        endif ()
+        FetchContent_Declare(
+                PICO_EXTRAS
+                GIT_REPOSITORY https://github.com/raspberrypi/pico-extras
+                GIT_TAG master
+        )
+        if (NOT PICO_EXTRAS)
+            message("Downloading PICO EXTRAS")
+            FetchContent_Populate(PICO_EXTRAS)
+            set(PICO_EXTRAS_PATH ${PICO_EXTRAS_SOURCE_DIR})
+        endif ()
+        set(FETCHCONTENT_BASE_DIR ${FETCHCONTENT_BASE_DIR_SAVE})
+    else ()
+        if (PICO_SDK_PATH AND EXISTS "${PICO_SDK_PATH}/../pico-extras")
+            set(PICO_EXTRAS_PATH ${PICO_SDK_PATH}/../pico-extras)
+            message("Defaulting PICO_EXTRAS_PATH as sibling of PICO_SDK_PATH: ${PICO_EXTRAS_PATH}")
+        else()
+            message(FATAL_ERROR
+                    "PICO EXTRAS location was not specified. Please set PICO_EXTRAS_PATH or set PICO_EXTRAS_FETCH_FROM_GIT to on to fetch from git."
+                    )
+        endif()
+    endif ()
+endif ()
+
+set(PICO_EXTRAS_PATH "${PICO_EXTRAS_PATH}" CACHE PATH "Path to the PICO EXTRAS")
+set(PICO_EXTRAS_FETCH_FROM_GIT "${PICO_EXTRAS_FETCH_FROM_GIT}" CACHE BOOL "Set to ON to fetch copy of PICO EXTRAS from git if not otherwise locatable")
+set(PICO_EXTRAS_FETCH_FROM_GIT_PATH "${PICO_EXTRAS_FETCH_FROM_GIT_PATH}" CACHE FILEPATH "location to download EXTRAS")
+
+get_filename_component(PICO_EXTRAS_PATH "${PICO_EXTRAS_PATH}" REALPATH BASE_DIR "${CMAKE_BINARY_DIR}")
+if (NOT EXISTS ${PICO_EXTRAS_PATH})
+    message(FATAL_ERROR "Directory '${PICO_EXTRAS_PATH}' not found")
+endif ()
+
+set(PICO_EXTRAS_PATH ${PICO_EXTRAS_PATH} CACHE PATH "Path to the PICO EXTRAS" FORCE)
+
+add_subdirectory(${PICO_EXTRAS_PATH} pico_extras)

firmware/sprig_hal/pico_sdk_import.cmake

@@ -0,0 +1,73 @@
+# This is a copy of <PICO_SDK_PATH>/external/pico_sdk_import.cmake
+
+# This can be dropped into an external project to help locate this SDK
+# It should be include()ed prior to project()
+
+if (DEFINED ENV{PICO_SDK_PATH} AND (NOT PICO_SDK_PATH))
+    set(PICO_SDK_PATH $ENV{PICO_SDK_PATH})
+    message("Using PICO_SDK_PATH from environment ('${PICO_SDK_PATH}')")
+endif ()
+
+if (DEFINED ENV{PICO_SDK_FETCH_FROM_GIT} AND (NOT PICO_SDK_FETCH_FROM_GIT))
+    set(PICO_SDK_FETCH_FROM_GIT $ENV{PICO_SDK_FETCH_FROM_GIT})
+    message("Using PICO_SDK_FETCH_FROM_GIT from environment ('${PICO_SDK_FETCH_FROM_GIT}')")
+endif ()
+
+if (DEFINED ENV{PICO_SDK_FETCH_FROM_GIT_PATH} AND (NOT PICO_SDK_FETCH_FROM_GIT_PATH))
+    set(PICO_SDK_FETCH_FROM_GIT_PATH $ENV{PICO_SDK_FETCH_FROM_GIT_PATH})
+    message("Using PICO_SDK_FETCH_FROM_GIT_PATH from environment ('${PICO_SDK_FETCH_FROM_GIT_PATH}')")
+endif ()
+
+set(PICO_SDK_PATH "${PICO_SDK_PATH}" CACHE PATH "Path to the Raspberry Pi Pico SDK")
+set(PICO_SDK_FETCH_FROM_GIT "${PICO_SDK_FETCH_FROM_GIT}" CACHE BOOL "Set to ON to fetch copy of SDK from git if not otherwise locatable")
+set(PICO_SDK_FETCH_FROM_GIT_PATH "${PICO_SDK_FETCH_FROM_GIT_PATH}" CACHE FILEPATH "location to download SDK")
+
+if (NOT PICO_SDK_PATH)
+    if (PICO_SDK_FETCH_FROM_GIT)
+        include(FetchContent)
+        set(FETCHCONTENT_BASE_DIR_SAVE ${FETCHCONTENT_BASE_DIR})
+        if (PICO_SDK_FETCH_FROM_GIT_PATH)
+            get_filename_component(FETCHCONTENT_BASE_DIR "${PICO_SDK_FETCH_FROM_GIT_PATH}" REALPATH BASE_DIR "${CMAKE_SOURCE_DIR}")
+        endif ()
+        # GIT_SUBMODULES_RECURSE was added in 3.17
+        if (${CMAKE_VERSION} VERSION_GREATER_EQUAL "3.17.0")
+            FetchContent_Declare(
+                    pico_sdk
+                    GIT_REPOSITORY https://github.com/raspberrypi/pico-sdk
+                    GIT_TAG master
+                    GIT_SUBMODULES_RECURSE FALSE
+            )
+        else ()
+            FetchContent_Declare(
+                    pico_sdk
+                    GIT_REPOSITORY https://github.com/raspberrypi/pico-sdk
+                    GIT_TAG master
+            )
+        endif ()
+
+        if (NOT pico_sdk)
+            message("Downloading Raspberry Pi Pico SDK")
+            FetchContent_Populate(pico_sdk)
+            set(PICO_SDK_PATH ${pico_sdk_SOURCE_DIR})
+        endif ()
+        set(FETCHCONTENT_BASE_DIR ${FETCHCONTENT_BASE_DIR_SAVE})
+    else ()
+        message(FATAL_ERROR
+                "SDK location was not specified. Please set PICO_SDK_PATH or set PICO_SDK_FETCH_FROM_GIT to on to fetch from git."
+                )
+    endif ()
+endif ()
+
+get_filename_component(PICO_SDK_PATH "${PICO_SDK_PATH}" REALPATH BASE_DIR "${CMAKE_BINARY_DIR}")
+if (NOT EXISTS ${PICO_SDK_PATH})
+    message(FATAL_ERROR "Directory '${PICO_SDK_PATH}' not found")
+endif ()
+
+set(PICO_SDK_INIT_CMAKE_FILE ${PICO_SDK_PATH}/pico_sdk_init.cmake)
+if (NOT EXISTS ${PICO_SDK_INIT_CMAKE_FILE})
+    message(FATAL_ERROR "Directory '${PICO_SDK_PATH}' does not appear to contain the Raspberry Pi Pico SDK")
+endif ()
+
+set(PICO_SDK_PATH ${PICO_SDK_PATH} CACHE PATH "Path to the Raspberry Pi Pico SDK" FORCE)
+
+include(${PICO_SDK_INIT_CMAKE_FILE})