aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorNick Moore <nicholasvmoore@gmail.com>2026-04-22 07:42:03 -0500
committerNick Moore <nicholasvmoore@gmail.com>2026-04-22 07:42:03 -0500
commit7fc0485f8e5bdcaf069d0cb833c51b010b9e0816 (patch)
treee7030b32025f88d2a62bb137dd3593df8600bf2a
parent8f5ed4b452deddfc285a9e3e5bd5ce2ccce6c74b (diff)
Initialize ESP32 project scaffold, tests, docs, and gitignoreHEADmaster
-rw-r--r--.envrc1
-rw-r--r--.gitignore27
-rw-r--r--AGENTS.md12
-rw-r--r--CMakeLists.txt4
-rw-r--r--README.md54
-rw-r--r--TODO.md13
-rw-r--r--components/sign_logic/CMakeLists.txt4
-rw-r--r--components/sign_logic/include/sign_logic.h30
-rw-r--r--components/sign_logic/sign_logic.c25
-rw-r--r--components/sign_logic/test/CMakeLists.txt5
-rw-r--r--components/sign_logic/test/test_sign_logic.c38
-rw-r--r--host_tests/CMakeLists.txt20
-rw-r--r--main/CMakeLists.txt4
-rw-r--r--main/main.c44
-rw-r--r--sdkconfig.defaults3
15 files changed, 284 insertions, 0 deletions
diff --git a/.envrc b/.envrc
new file mode 100644
index 0000000..aebcef4
--- /dev/null
+++ b/.envrc
@@ -0,0 +1 @@
+source /opt/esp-idf/export.sh
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..97243f4
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,27 @@
+# ESP-IDF build artifacts
+build/
+build_*/
+
+# Host test build artifacts
+build_host_tests/
+
+# ESP-IDF generated config
+sdkconfig
+sdkconfig.old
+
+# CMake artifacts
+CMakeCache.txt
+CMakeFiles/
+cmake_install.cmake
+install_manifest.txt
+compile_commands.json
+
+# direnv
+.direnv/
+.envrc.local
+
+# OS/editor files
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..9a00628
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,12 @@
+# esp32-onair-sign
+
+This is a project that will power an on-air sign that can be controlled by a smartphone.
+
+## Hardware
+
+### ESP32
+
+We will write the code for the ESP32 in C.
+Use Bluetooth Lowe Energy (BLE) to communicate with the smartphone.
+
+Write unit tests for this project
diff --git a/CMakeLists.txt b/CMakeLists.txt
new file mode 100644
index 0000000..3dfafa8
--- /dev/null
+++ b/CMakeLists.txt
@@ -0,0 +1,4 @@
+cmake_minimum_required(VERSION 3.16)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(iot_onair_sign)
diff --git a/README.md b/README.md
index 1ac5fac..ed29e87 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,55 @@
# iot-onair-sign
+
+ESP32 firmware project for an on-air sign controlled from a smartphone over BLE.
+
+## Dependencies
+
+Required tools:
+- `esp-idf` (v5.x+)
+- `direnv`
+
+Note: ESP-IDF provides the required build toolchain (including CMake, Ninja, and compiler tools), so these do not need separate system installation.
+
+## Environment setup (recommended)
+
+This repo includes a `.envrc` file that loads ESP-IDF for this project only.
+
+1. Install and enable `direnv` in your shell.
+2. From the project root, allow the environment once:
+
+```bash
+direnv allow
+```
+
+After that, entering this directory will automatically load ESP-IDF variables.
+
+## Build
+
+1. Enter the project directory (direnv will auto-load the environment).
+2. Set the target (first time only):
+
+```bash
+idf.py set-target esp32
+```
+
+3. Build:
+
+```bash
+idf.py build
+```
+
+## Flash and monitor
+
+```bash
+idf.py -p /dev/ttyUSB0 flash monitor
+```
+
+(Adjust serial port as needed.)
+
+## Run unit tests (host)
+
+```bash
+cmake -S host_tests -B build_host_tests
+cmake --build build_host_tests
+ctest --test-dir build_host_tests --output-on-failure
+```
diff --git a/TODO.md b/TODO.md
new file mode 100644
index 0000000..fb4c2af
--- /dev/null
+++ b/TODO.md
@@ -0,0 +1,13 @@
+- Create initial ESP32 project structure (src/, include/, test/, CMakeLists.txt)
+- Set up ESP-IDF build configuration and target board settings
+- Implement BLE GATT server for smartphone control
+- Define BLE service/characteristics for sign state and brightness
+- Add command parser and validation for incoming BLE writes
+- Implement GPIO/LED control logic for ON-AIR sign output
+- Add configuration storage (e.g., NVS) for persisted settings
+- Add connection status handling and safe default behavior on disconnect
+- Write unit tests for command parsing and state transition logic
+- Add hardware abstraction so core logic can be tested without ESP32 hardware
+- Add basic integration tests/smoke tests for BLE control flow
+- Add README setup/build/flash/test instructions
+- Add CI workflow for build and unit test execution
diff --git a/components/sign_logic/CMakeLists.txt b/components/sign_logic/CMakeLists.txt
new file mode 100644
index 0000000..53e9a30
--- /dev/null
+++ b/components/sign_logic/CMakeLists.txt
@@ -0,0 +1,4 @@
+idf_component_register(
+ SRCS "sign_logic.c"
+ INCLUDE_DIRS "include"
+)
diff --git a/components/sign_logic/include/sign_logic.h b/components/sign_logic/include/sign_logic.h
new file mode 100644
index 0000000..ca296cb
--- /dev/null
+++ b/components/sign_logic/include/sign_logic.h
@@ -0,0 +1,30 @@
+#pragma once
+
+#include <stdbool.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define SIGN_BRIGHTNESS_MIN 0u
+#define SIGN_BRIGHTNESS_MAX 100u
+#define SIGN_BRIGHTNESS_DEFAULT 75u
+
+typedef struct {
+ bool is_on_air;
+ uint8_t brightness;
+} sign_state_t;
+
+typedef enum {
+ SIGN_OK = 0,
+ SIGN_ERR_NULL = 1,
+ SIGN_ERR_RANGE = 2,
+} sign_result_t;
+
+sign_result_t sign_set_on_air(sign_state_t *state, bool on_air);
+sign_result_t sign_set_brightness(sign_state_t *state, uint8_t brightness);
+
+#ifdef __cplusplus
+}
+#endif
diff --git a/components/sign_logic/sign_logic.c b/components/sign_logic/sign_logic.c
new file mode 100644
index 0000000..a8ceb0b
--- /dev/null
+++ b/components/sign_logic/sign_logic.c
@@ -0,0 +1,25 @@
+#include <stddef.h>
+
+#include "sign_logic.h"
+
+sign_result_t sign_set_on_air(sign_state_t *state, bool on_air) {
+ if (state == NULL) {
+ return SIGN_ERR_NULL;
+ }
+
+ state->is_on_air = on_air;
+ return SIGN_OK;
+}
+
+sign_result_t sign_set_brightness(sign_state_t *state, uint8_t brightness) {
+ if (state == NULL) {
+ return SIGN_ERR_NULL;
+ }
+
+ if (brightness > SIGN_BRIGHTNESS_MAX) {
+ return SIGN_ERR_RANGE;
+ }
+
+ state->brightness = brightness;
+ return SIGN_OK;
+}
diff --git a/components/sign_logic/test/CMakeLists.txt b/components/sign_logic/test/CMakeLists.txt
new file mode 100644
index 0000000..2f6f0f1
--- /dev/null
+++ b/components/sign_logic/test/CMakeLists.txt
@@ -0,0 +1,5 @@
+idf_component_register(
+ SRCS "test_sign_logic.c"
+ INCLUDE_DIRS "../include"
+ REQUIRES unity sign_logic
+)
diff --git a/components/sign_logic/test/test_sign_logic.c b/components/sign_logic/test/test_sign_logic.c
new file mode 100644
index 0000000..9985702
--- /dev/null
+++ b/components/sign_logic/test/test_sign_logic.c
@@ -0,0 +1,38 @@
+#include <assert.h>
+#include <stdbool.h>
+#include <stdio.h>
+
+#include "sign_logic.h"
+
+static void test_sign_set_on_air_updates_state(void) {
+ sign_state_t state = {.is_on_air = false, .brightness = SIGN_BRIGHTNESS_DEFAULT};
+
+ assert(sign_set_on_air(&state, true) == SIGN_OK);
+ assert(state.is_on_air == true);
+}
+
+static void test_sign_set_brightness_rejects_out_of_range(void) {
+ sign_state_t state = {.is_on_air = false, .brightness = SIGN_BRIGHTNESS_DEFAULT};
+
+ assert(sign_set_brightness(&state, 101) == SIGN_ERR_RANGE);
+ assert(state.brightness == SIGN_BRIGHTNESS_DEFAULT);
+}
+
+static void test_sign_set_brightness_accepts_valid_range(void) {
+ sign_state_t state = {.is_on_air = false, .brightness = SIGN_BRIGHTNESS_DEFAULT};
+
+ assert(sign_set_brightness(&state, 0) == SIGN_OK);
+ assert(state.brightness == 0);
+
+ assert(sign_set_brightness(&state, 100) == SIGN_OK);
+ assert(state.brightness == 100);
+}
+
+int main(void) {
+ test_sign_set_on_air_updates_state();
+ test_sign_set_brightness_rejects_out_of_range();
+ test_sign_set_brightness_accepts_valid_range();
+
+ printf("sign_logic tests passed\n");
+ return 0;
+}
diff --git a/host_tests/CMakeLists.txt b/host_tests/CMakeLists.txt
new file mode 100644
index 0000000..eb5fabe
--- /dev/null
+++ b/host_tests/CMakeLists.txt
@@ -0,0 +1,20 @@
+cmake_minimum_required(VERSION 3.16)
+project(sign_logic_host_tests C)
+
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_C_STANDARD_REQUIRED ON)
+
+enable_testing()
+
+add_executable(test_sign_logic
+ ../components/sign_logic/sign_logic.c
+ ../components/sign_logic/test/test_sign_logic.c
+)
+
+target_include_directories(test_sign_logic PRIVATE
+ ../components/sign_logic/include
+)
+
+target_compile_options(test_sign_logic PRIVATE -Wall -Wextra -Werror)
+
+add_test(NAME test_sign_logic COMMAND test_sign_logic)
diff --git a/main/CMakeLists.txt b/main/CMakeLists.txt
new file mode 100644
index 0000000..e476bb3
--- /dev/null
+++ b/main/CMakeLists.txt
@@ -0,0 +1,4 @@
+idf_component_register(
+ SRCS "main.c"
+ REQUIRES bt nvs_flash sign_logic
+)
diff --git a/main/main.c b/main/main.c
new file mode 100644
index 0000000..e3117a2
--- /dev/null
+++ b/main/main.c
@@ -0,0 +1,44 @@
+#include <stdbool.h>
+#include <stdint.h>
+
+#include "esp_err.h"
+#include "esp_log.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "nvs_flash.h"
+#include "sign_logic.h"
+
+static const char *TAG = "onair_main";
+
+static esp_err_t init_storage(void) {
+ esp_err_t err = nvs_flash_init();
+ if (err == ESP_ERR_NVS_NO_FREE_PAGES || err == ESP_ERR_NVS_NEW_VERSION_FOUND) {
+ ESP_ERROR_CHECK(nvs_flash_erase());
+ err = nvs_flash_init();
+ }
+ return err;
+}
+
+static void init_ble(void) {
+ // TODO: Add BLE controller + Bluedroid/NimBLE initialization.
+ // TODO: Register GATT service + characteristics for sign control.
+ ESP_LOGI(TAG, "BLE initialization placeholder");
+}
+
+void app_main(void) {
+ ESP_ERROR_CHECK(init_storage());
+
+ sign_state_t state = {
+ .is_on_air = false,
+ .brightness = SIGN_BRIGHTNESS_DEFAULT,
+ };
+
+ ESP_LOGI(TAG, "Boot state: on_air=%d brightness=%u", state.is_on_air, state.brightness);
+
+ init_ble();
+
+ while (true) {
+ // TODO: Main runtime tasks and event loop hooks.
+ vTaskDelay(pdMS_TO_TICKS(1000));
+ }
+}
diff --git a/sdkconfig.defaults b/sdkconfig.defaults
new file mode 100644
index 0000000..3cb84b5
--- /dev/null
+++ b/sdkconfig.defaults
@@ -0,0 +1,3 @@
+# Default configuration values for local development.
+# Override with `idf.py menuconfig` as needed.
+CONFIG_LOG_DEFAULT_LEVEL_INFO=y