| name | arcana-stm32-developer-skill |
| description | STM32 embedded development guide based on Arcana Embedded STM32 architecture. Provides comprehensive support for Observable Pattern on STM32F051C8 (8KB RAM, 64KB Flash) with FreeRTOS, zero-copy model passing, dual-priority queuing, static allocation, and ISR-safe publishing. Suitable for embedded C++14 development, architecture design, code review, memory optimization, and real-time debugging. |
| allowed-tools | ["Read","Grep","Glob","Bash","Write","Edit"] |
STM32 Developer Skill
Professional STM32/FreeRTOS/C++14 embedded development skill based on Arcana Embedded STM32 production architecture.
⚡ Workflow — Always Start From the Reference Project
Never start an STM32 project from scratch. Clone the validated reference project and adapt it — the linker script, FreeRTOS config, and Observable infrastructure are production-validated and easy to break by hand-assembly.
- Clone first — follow Project Setup - CRITICAL below for the full clone/re-init/KEEP/REPLACE procedure.
- Build the untouched clone first — establish a green
make + arm-none-eabi-size baseline BEFORE changing anything. If the pristine clone doesn't build, fix your toolchain (not the project).
- Then adapt — replace only the example services/models listed in Project Setup; keep the core architecture files. When adding a NEW service/sensor/peripheral module, do it by copying the nearest working module — see Adding a module = copy the nearest working module below.
🔁 Adding a module = copy the nearest working module (NOT from scratch)
When you add a new sensor / command / peripheral module, do NOT re-create it from memory. Copy the nearest already-working module of the same kind in the reference firmware, then adapt it.
- Find the closest conformant module already in the reference — e.g. the existing
CounterService (observer) or TimerService (publisher) built on Observable<T>, which already follows the project's pattern (zero-copy const T& model passing, static allocation, ISR-safe publishFromISR + portYIELD_FROM_ISR, the Observable/dispatcher boundary).
- Duplicate its ENTIRE file set (the model struct in
Core/Inc/Models.hpp with its static_assert size/trivially-copyable guards + ModelType enum + QueueItem union entry; the service header Core/Inc/<Service>.hpp + source Core/Src/<Service>.cpp; the Observable<Model> member, Observer registration and task wiring in Core/Src/App.cpp; the .cpp added to the Makefile build; and the arm-none-eabi-size RAM/Flash budget re-check) 1:1, keeping the established pattern (zero-copy model, static allocation, ISR-safe publish, the Observable/Port boundary).
- Rename + adapt to the new sensor/command/peripheral (IDs, registers, payload types, registration).
- Diff against the original to confirm nothing was dropped — same pattern, same allocation discipline, same tests.
Why this is mandatory: re-deriving the pattern each time makes every step a chance to break the discipline the architecture depends on (dynamic allocation creeping in, non-ISR-safe publish, skipping the Observable boundary, dropping the host test) — deviations that may compile but violate the real-time/memory constraints. Copying a known-good module carries that discipline in by construction.
Supporting files — load on demand
| File | When to load |
|---|
patterns/observable-pattern.md | Implementing or debugging the Observable/dispatcher pattern |
patterns.md | General architecture patterns overview |
examples.md | Concrete code examples for services, models, observers |
checklists/production-ready.md | Pre-release / production readiness review |
verification/commands.md | Build, size, and verification commands |
reference.md | API and configuration reference details |
Quick Reference Card
New Observer Checklist:
1. Define callback signature: void (*callback)(const ModelType&, void*)
2. Create observer struct with callback + context pointer
3. Subscribe via observable.subscribe(&observer)
4. Verify observer count <= MAX_OBSERVERS (4)
5. Implement callback with const reference (zero-copy)
6. Test with both normal and high-priority publish
7. Verify stack usage with arm-none-eabi-size
New Model Checklist:
1. Define struct in Models.hpp (POD type, no heap)
2. Keep sizeof(Model) <= queue item size
3. Add static_assert for size verification
4. Register model type in Observable<T> template instantiation
5. Verify total RAM impact: sizeof(Model) * (HIGH_QUEUE + NORMAL_QUEUE)
6. Test zero-copy passing through publish/notify chain
Quick Diagnosis:
| Symptom | Check Command |
|---|
| Queue overflow | Check getStats() for dropped events |
| Stack overflow | arm-none-eabi-size -A build/*.elf check stack sections |
| ISR latency spike | Verify publishFromISR uses portYIELD_FROM_ISR |
| Observer not called | Check subscribe count, verify dispatcher task running |
| Hard fault | Check stack sizes in FreeRTOSConfig.h, alignment of models |
| High CPU usage | Verify osDelay or xQueueReceive with portMAX_DELAY |
Rules Priority
CRITICAL (Must Fix Immediately)
| Rule | Description | Verification |
|---|
| No Heap Allocation | NEVER use malloc, new, std::vector, std::string at runtime | grep -rn "malloc|new |std::vector|std::string" Core/ |
| Stack Overflow Guard | Every task stack must be verified against worst-case depth | arm-none-eabi-size -A build/*.elf |
| ISR Safety | ISR code must ONLY call publishFromISR / publishHighPriorityFromISR | grep -rn "publish(" Core/Src/*.cpp in ISR context |
| Observer Limit | MAX_OBSERVERS = 4 per Observable, NEVER exceed | Check subscribe() return values |
| Queue Size Bounds | High=4, Normal=8, fixed at compile time | Verify in Observable.hpp defines |
| RAM Budget | Total RAM usage MUST stay under 8,192 bytes (8KB) | arm-none-eabi-size build/*.elf |
| Flash Budget | Total Flash usage MUST stay under 65,536 bytes (64KB) | arm-none-eabi-size build/*.elf |
| Volatile for ISR | Shared variables between ISR and task MUST be volatile | Review ISR-shared globals |
| Critical Section | Shared data access must use taskENTER_CRITICAL / taskEXIT_CRITICAL | Review multi-task shared data |
IMPORTANT (Should Fix Before PR)
| Rule | Description | Verification |
|---|
| Zero-Copy Model | Models passed by const reference, never copied unnecessarily | Check callback signatures |
| Error Callback | Set error callback via setErrorCallback() for queue overflow | Verify error handling path |
| Static Allocation | All objects allocated statically (global/static scope) | grep -rn "new |malloc" Core/ |
| Priority Inversion | High-priority events processed before normal | Test dual-priority ordering |
| FreeRTOS Config | Heap scheme = heap_4, tick rate = 1000Hz | Check FreeRTOSConfig.h |
| Model Alignment | Structs must be properly aligned for ARM Cortex-M0 | Check __attribute__((aligned)) |
| Const Correctness | Observer callbacks receive const T& | Review all callback signatures |
RECOMMENDED (Nice to Have)
| Rule | Description |
|---|
| Performance Logging | Track event latency with DWT cycle counter |
| Watchdog Timer | IWDG configured for task hang detection |
| Power Management | Use __WFI() in idle task for low power |
| Debug UART | Printf retargeting for debug output |
Error Handling Pattern
Observable Error Types
enum class ObservableError : uint8_t {
QueueFull,
QueueNotReady,
InvalidModel,
NoObservers
};
Error Callback Pattern
using ErrorCallback = void (*)(ObservableError error, void* context);
class ObservableDispatcher {
public:
void setErrorCallback(ErrorCallback cb, void* ctx) {
errorCallback_ = cb;
errorContext_ = ctx;
}
private:
ErrorCallback errorCallback_ = nullptr;
void* errorContext_ = nullptr;
void reportError(ObservableError error) {
if (errorCallback_) {
errorCallback_(error, errorContext_);
}
}
};
Queue Overflow Handling
void onObservableError(ObservableError error, void* context) {
switch (error) {
case ObservableError::QueueFull:
errorStats.droppedEvents++;
break;
case ObservableError::QueueNotReady:
Error_Handler();
break;
case ObservableError::InvalidModel:
assert(false);
break;
case ObservableError::NoObservers:
break;
}
}
dispatcher.setErrorCallback(onObservableError, nullptr);
Memory Budget
RAM Breakdown (STM32F051C8 - 8,192 bytes total)
| Component | Bytes | % of Total |
|---|
| FreeRTOS Kernel | ~1,200 | 14.6% |
| Task Stacks (3 tasks) | ~1,536 | 18.8% |
| Observable Dispatcher | ~320 | 3.9% |
| Event Queues (High+Normal) | ~480 | 5.9% |
| Observer Arrays | ~128 | 1.6% |
| Model Instances | ~192 | 2.3% |
| Application Variables | ~500 | 6.1% |
| Total Used | ~4,356 | 53.2% |
| Free | ~3,836 | 46.8% |
Flash Breakdown (STM32F051C8 - 65,536 bytes total)
| Component | Bytes | % of Total |
|---|
| Startup + Vector Table | ~512 | 0.8% |
| HAL Drivers | ~4,096 | 6.3% |
| FreeRTOS | ~5,120 | 7.8% |
| Observable Framework | ~2,560 | 3.9% |
| Application Logic | ~3,680 | 5.6% |
| C++ Runtime (minimal) | ~1,000 | 1.5% |
| Total Used | ~16,968 | 25.9% |
| Free | ~48,568 | 74.1% |
Stack Size Guidelines
| Task | Stack Words | Stack Bytes | Purpose |
|---|
| Dispatcher | 128 | 512 | Event dispatch loop |
| TimerService | 128 | 512 | Timer tick publisher |
| CounterService | 128 | 512 | Event observer/counter |
| Idle Task | 64 | 256 | FreeRTOS idle |
Memory Rules
RULE 1: NEVER exceed 75% RAM usage (6,144 bytes) - leave headroom for stack growth
RULE 2: Each new model adds: sizeof(Model) * 12 bytes to queue storage
RULE 3: Each new observer adds: 8 bytes (callback + context pointer)
RULE 4: Each new task adds: stack_words * 4 + 88 bytes (TCB)
Observable Pattern Architecture
System Overview
STM32F051C8 Observable Architecture
================================================================
+-----------------+ +------------------+
| TimerService | | ISR Handler |
| (Publisher) | | (TIM/GPIO/UART) |
+--------+--------+ +--------+---------+
| |
| publish() | publishFromISR()
| |
+--------v-----------------------v---------+
| ObservableDispatcher |
| +-----------------------------------+ |
| | High Priority Queue (4 items) | |
| | [evt][evt][evt][evt] | |
| +-----------------------------------+ |
| | Normal Priority Queue (8 items) | |
| | [evt][evt][evt][evt][evt]... | |
| +-----------------------------------+ |
| | |
| dispatch task |
| (FreeRTOS) |
+------------------+-----------------------+
|
| notify() - zero copy
|
+------------+------------+
| | |
+-----v----+ +----v-----+ +---v--------+
| Counter | | Time | | Observer |
| Service | | Display | | N (max 4) |
| Observer | | Observer | | |
+----------+ +----------+ +------------+
Event Flow (Normal Priority)
Publisher Task Dispatcher Task Observer Callbacks
============= =============== ==================
| | |
1. publish(model) | |
| | |
2. xQueueSend | |
(normalQueue) | |
| | |
| 3. xQueueReceive |
| (blocking) |
| | |
| 4. for each observer: |
| |------ notify(model) ---->|
| | (const T&) |
| | 5. callback(model, ctx)
| |<-------------------------|
| | |
Event Flow (ISR to Task)
ISR Context Dispatcher Task Observer Callbacks
=========== =============== ==================
| | |
1. publishFromISR(model) | |
| | |
2. xQueueSendFromISR | |
(highPriorityQueue) | |
| | |
3. portYIELD_FROM_ISR | |
(if higher priority | |
task woken) | |
| 4. xQueueReceive |
| (high queue first) |
| | |
| 5. notify all observers |
| |------ callback --------->|
| | |
Dual-Priority Queue System
Queue Configuration
static constexpr uint8_t HIGH_PRIORITY_QUEUE_SIZE = 4;
static constexpr uint8_t NORMAL_PRIORITY_QUEUE_SIZE = 8;
struct QueueItem {
uint8_t modelType;
uint8_t padding[3];
union {
TimeModel time;
CounterModel counter;
} data;
};
Priority Dispatch Logic
void ObservableDispatcher::dispatchTask(void* param) {
auto* self = static_cast<ObservableDispatcher*>(param);
for (;;) {
QueueItem item;
while (xQueueReceive(self->highQueue_, &item, 0) == pdTRUE) {
self->dispatch(item);
}
if (xQueueReceive(self->normalQueue_, &item, portMAX_DELAY) == pdTRUE) {
self->dispatch(item);
}
}
}
Queue Usage Guidelines
| Priority | Queue Size | Use Case | Latency |
|---|
| High | 4 items | ISR events, safety-critical | ~22us |
| Normal | 8 items | Periodic updates, UI refresh | ~50us |
WARNING: Events are LOST when queue is full.
- High priority: max 4 pending events before overflow
- Normal priority: max 8 pending events before overflow
- Use hasQueueSpace() to check before publishing non-critical events
- NEVER check hasQueueSpace() from ISR (not ISR-safe for checking)
FreeRTOS Integration
Task Configuration
#define configUSE_PREEMPTION 1
#define configCPU_CLOCK_HZ (48000000)
#define configTICK_RATE_HZ ((TickType_t)1000)
#define configMAX_PRIORITIES (7)
#define configMINIMAL_STACK_SIZE ((uint16_t)64)
#define configTOTAL_HEAP_SIZE ((size_t)4096)
#define configMAX_TASK_NAME_LEN (8)
#define configUSE_MUTEXES 1
#define configUSE_COUNTING_SEMAPHORES 1
#define configUSE_QUEUE_SETS 0
#define configUSE_TIMERS 1
#define configTIMER_TASK_STACK_DEPTH 64
#define configUSE_MALLOC_FAILED_HOOK 1
#define configCHECK_FOR_STACK_OVERFLOW 2
#define configSUPPORT_STATIC_ALLOCATION 1
#define configSUPPORT_DYNAMIC_ALLOCATION 1
Task Creation Pattern
static StaticTask_t dispatcherTaskTCB;
static StackType_t dispatcherTaskStack[128];
static StaticTask_t timerTaskTCB;
static StackType_t timerTaskStack[128];
void App::init() {
dispatcher_.start(
"Dispatch",
osPriorityAboveNormal,
dispatcherTaskStack,
sizeof(dispatcherTaskStack) / sizeof(StackType_t),
&dispatcherTaskTCB
);
xTaskCreateStatic(
TimerService::taskEntry,
"Timer",
128,
&timerService_,
osPriorityNormal,
timerTaskStack,
&timerTaskTCB
);
}
FreeRTOS Queue Integration
class ObservableDispatcher {
private:
QueueHandle_t highQueue_;
QueueHandle_t normalQueue_;
static StaticQueue_t highQueueBuffer_;
static StaticQueue_t normalQueueBuffer_;
static uint8_t highQueueStorage_[HIGH_PRIORITY_QUEUE_SIZE * sizeof(QueueItem)];
static uint8_t normalQueueStorage_[NORMAL_PRIORITY_QUEUE_SIZE * sizeof(QueueItem)];
public:
void init() {
highQueue_ = xQueueCreateStatic(
HIGH_PRIORITY_QUEUE_SIZE,
sizeof(QueueItem),
highQueueStorage_,
&highQueueBuffer_
);
normalQueue_ = xQueueCreateStatic(
NORMAL_PRIORITY_QUEUE_SIZE,
sizeof(QueueItem),
normalQueueStorage_,
&normalQueueBuffer_
);
}
};
ISR Safety Patterns
Publishing from ISR
void TIM2_IRQHandler(void) {
HAL_TIM_IRQHandler(&htim2);
}
void HAL_TIM_PeriodElapsedCallback(TIM_HandleTypeDef* htim) {
if (htim->Instance == TIM2) {
TimeModel model;
model.seconds = tickCount / 1000;
model.milliseconds = tickCount % 1000;
BaseType_t xHigherPriorityTaskWoken = pdFALSE;
observable.publishFromISR(model, &xHigherPriorityTaskWoken);
portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
}
}
ISR-Safe API Summary
| Regular API | ISR-Safe API | Notes |
|---|
publish() | publishFromISR() | Must pass pxHigherPriorityTaskWoken |
publishHighPriority() | publishHighPriorityFromISR() | For safety-critical ISR events |
taskENTER_CRITICAL() | taskENTER_CRITICAL_FROM_ISR() | Returns interrupt mask |
xQueueSend() | xQueueSendFromISR() | Zero timeout only |
xSemaphoreGive() | xSemaphoreGiveFromISR() | Must check task woken |
ISR Timing Constraints
ARM Cortex-M0 ISR Guidelines:
- ISR body: < 10us (480 cycles at 48MHz)
- publishFromISR: ~2us (96 cycles) - just a queue enqueue
- portYIELD_FROM_ISR: ~1us if context switch needed
- Total ISR time with publish: ~3-5us
NEVER do in ISR:
- Floating point operations (Cortex-M0 has no FPU)
- Memory allocation (malloc/new)
- Blocking calls (delay, semaphore wait)
- Printf / UART transmit with blocking
- Complex computation (> 480 cycles)
Static Allocation Patterns
Global Static Objects
class App {
private:
ObservableDispatcher dispatcher_;
Observable<TimeModel> timeObservable_;
Observable<CounterModel> counterObservable_;
TimerService timerService_;
CounterService counterService_;
TimeDisplayService timeDisplayService_;
Observer<TimeModel> counterObserver_;
Observer<TimeModel> displayObserver_;
Observer<CounterModel> counterDisplayObserver_;
public:
void init();
void run();
};
static App app;
int main(void) {
HAL_Init();
SystemClock_Config();
app.init();
app.run();
}
Static Buffer Pattern
class TimeDisplayService {
private:
char displayBuffer_[32];
void formatTime(const TimeModel& model) {
snprintf(displayBuffer_, sizeof(displayBuffer_),
"%02u:%02u:%02u.%03u",
model.hours, model.minutes,
model.seconds, model.milliseconds);
}
};
Static Container Pattern
template <typename T, uint8_t MaxSize>
class StaticArray {
private:
T items_[MaxSize];
uint8_t count_ = 0;
public:
bool add(const T& item) {
if (count_ >= MaxSize) return false;
items_[count_++] = item;
return true;
}
bool remove(uint8_t index) {
if (index >= count_) return false;
for (uint8_t i = index; i < count_ - 1; i++) {
items_[i] = items_[i + 1];
}
count_--;
return true;
}
uint8_t size() const { return count_; }
const T& operator[](uint8_t index) const { return items_[index]; }
T& operator[](uint8_t index) { return items_[index]; }
};
Zero-Copy Model Passing
Model Definition Pattern
struct TimeModel {
uint8_t hours;
uint8_t minutes;
uint8_t seconds;
uint16_t milliseconds;
};
static_assert(sizeof(TimeModel) <= 8, "TimeModel exceeds queue item budget");
static_assert(std::is_trivially_copyable<TimeModel>::value,
"TimeModel must be trivially copyable for queue transport");
struct CounterModel {
uint32_t count;
uint32_t overflowCount;
};
static_assert(sizeof(CounterModel) <= 8, "CounterModel exceeds queue item budget");
static_assert(std::is_trivially_copyable<CounterModel>::value,
"CounterModel must be trivially copyable for queue transport");
Zero-Copy Observer Callback
using ObserverCallback = void (*)(const TimeModel& model, void* context);
void onTimeUpdate(const TimeModel& model, void* context) {
auto* service = static_cast<CounterService*>(context);
service->processTime(model);
}
Queue Transport (Single Copy)
Model lifecycle:
1. Publisher creates model on stack [stack copy]
2. xQueueSend copies model into queue [queue copy] -- ONLY COPY
3. Dispatcher reads from queue [reference to queue storage]
4. Observer callback receives const ref [zero copy - same memory]
5. After all observers notified, queue slot is freed
Total copies: 1 (publisher stack -> queue)
Observer access: 0 copies (const reference to queue storage)
Performance Metrics
Measured Performance (STM32F051C8 @ 48MHz)
| Metric | Value | Notes |
|---|
| Event latency (publish to notify) | ~22us | Normal priority, single observer |
| High-priority event latency | ~12us | Pre-empts normal processing |
| Context switch time | ~10us | FreeRTOS task switch |
| publishFromISR time | ~2us | Queue enqueue only |
| CPU usage (idle) | < 1% | With 3 services running |
| Queue throughput | ~45K events/sec | Normal priority, sustained |
| Observer notify overhead | ~1us per observer | Callback dispatch |
Performance Rules
RULE 1: Observer callbacks MUST complete in < 100us
RULE 2: ISR publish MUST complete in < 5us
RULE 3: Total ISR time MUST be < 10us
RULE 4: Dispatcher task should not block for > 1ms on any single event
RULE 5: If CPU usage > 10%, review observer callback complexity
Code Review Checklist
Required Items
Performance Checks
Safety Checks
Common Issues
Hard Fault / Crash
| Cause | Solution |
|---|
| Stack overflow | Increase task stack size, reduce local variables |
| Null function pointer | Validate observer callback before calling |
| Unaligned access | Use __attribute__((aligned(4))) on structs |
| ISR calling non-ISR API | Switch to *FromISR() variants |
| Heap exhaustion | Eliminate dynamic allocation, use static buffers |
Queue Issues
| Cause | Solution |
|---|
| Events dropped | Increase queue size or reduce publish rate |
| Observer not notified | Verify subscribe() succeeded (check return value) |
| Stale data in observer | Model valid only during callback - copy if needed |
| Priority inversion | Check dispatcher task priority is highest among app tasks |
Build Issues
| Cause | Solution |
|---|
| Linker error: undefined reference | Check .cpp file added to build |
| C++ exception support bloat | Use -fno-exceptions -fno-rtti flags |
| Flash overflow | Enable -Os, remove unused HAL modules |
| RAM overflow | Reduce stack sizes, remove unused variables |
FreeRTOS Issues
| Cause | Solution |
|---|
| Task not running | Check xTaskCreate return value, verify priority |
| Deadlock | Review mutex/semaphore acquisition order |
| Timer callback late | Increase timer task priority |
| Idle task starved | Reduce high-priority task CPU usage |
Instructions
When handling STM32/FreeRTOS/C++14 embedded development tasks, follow these principles:
Quick Verification Commands
Use these commands to quickly check for common issues:
grep -rn "malloc\|calloc\|realloc\|free\b\|new \|delete " Core/Inc/ Core/Src/
grep -rn "std::vector\|std::string\|std::map\|std::list\|std::shared_ptr\|std::unique_ptr" Core/
grep -rn "\.publish(" Core/Src/ | grep -i "irq\|handler\|callback"
grep -rn "subscribe(" Core/Src/*.cpp | wc -l
grep -rn "static_assert.*sizeof\|static_assert.*trivially" Core/Inc/Models.hpp
arm-none-eabi-size -A build/*.elf
grep -rn "volatile" Core/Inc/ Core/Src/
grep -rn "configCHECK_FOR_STACK_OVERFLOW" Core/Inc/FreeRTOSConfig.h
grep -rn "StackType_t\|configMINIMAL_STACK_SIZE\|stack_size\|stackSize" Core/
grep -rn "float\|double" Core/Src/*IRQ* Core/Src/*Handler*
make -j$(nproc 2>/dev/null || sysctl -n hw.ncpu) 2>&1 | tail -20
CRITICAL: All heap allocation checks MUST return empty. Any use of malloc, new, std::vector, or std::string in application code is a critical defect.
If any of these return unexpected results, FIX THEM before completing the task.
Project Setup - CRITICAL
IMPORTANT: This reference project has been validated with tested STM32CubeIDE settings and linker configuration. NEVER reconfigure the memory layout, linker script, or FreeRTOS heap scheme, or it will cause runtime crashes.
Step 1: Clone the reference project
git clone https://github.com/jrjohn/arcana-embedded-stm32.git [new-project-directory]
cd [new-project-directory]
Step 2: Reinitialize Git
rm -rf .git
git init
git add .
git commit -m "Initial commit from arcana-embedded-stm32 template"
Step 3: Open in STM32CubeIDE
- Import as existing STM32CubeIDE project
- Verify target: STM32F051C8Tx
- Verify toolchain: GNU ARM Embedded 10.3+
Step 4: Modify for your application
Only modify the following:
- Service classes in
Core/Src/ and Core/Inc/
- Model definitions in
Core/Inc/Models.hpp
- Observer registrations in
Core/Src/App.cpp
- Pin/peripheral configuration via STM32CubeMX (.ioc file)
Core architecture files to KEEP (do not delete):
Core/Inc/Observable.hpp - Observable pattern coreCore/Src/Observable.cpp - Observable implementationCore/Inc/App.hpp - Application interfaceCore/Src/App.cpp - Application setupCore/Inc/FreeRTOSConfig.h - RTOS configurationSTM32F051C8TX_FLASH.ld - Linker scriptDrivers/ - STM32 HAL driversMiddlewares/ - FreeRTOS kernel
Example files to REPLACE:
Core/Inc/TimerService.hpp - Replace with your publisherCore/Inc/CounterService.hpp - Replace with your observerCore/Inc/TimeDisplayService.hpp - Replace with your observerCore/Inc/Models.hpp - Replace with your model definitionsCore/Src/TimerService.cpp - Replace publisher implementationCore/Src/CounterService.cpp - Replace observer implementationCore/Src/TimeDisplayService.cpp - Replace observer implementation
Step 5: Build and verify
make -j$(nproc 2>/dev/null || sysctl -n hw.ncpu)
arm-none-eabi-size build/*.elf
Note: if the project is built inside STM32CubeIDE (managed build), the IDE drives the
build itself — the make invocation above only applies to the Makefile/CLI build path.
Prohibited Actions
- DO NOT use
malloc, new, or any dynamic allocation in application code
- DO NOT modify the linker script memory regions
- DO NOT change FreeRTOS heap scheme from
heap_4
- DO NOT add C++ exceptions (
-fno-exceptions is required)
- DO NOT add RTTI (
-fno-rtti is required)
- DO NOT use
std::string, std::vector, or STL containers with heap allocation
- DO NOT exceed MAX_OBSERVERS (4) per Observable instance
Allowed Modifications
- Add new Observer/Publisher service classes (following existing patterns)
- Add new Model types in
Models.hpp (with static_assert for size)
- Modify peripheral configuration (GPIO, UART, TIM, SPI, I2C)
- Adjust task priorities and stack sizes (with verification)
- Add HAL peripheral initialization code
Project Structure
arcana-embedded-stm32/
├── Core/
│ ├── Inc/
│ │ ├── Observable.hpp # Observable pattern core template
│ │ ├── Models.hpp # All model/event definitions
│ │ ├── TimerService.hpp # Publisher: timer tick events
│ │ ├── CounterService.hpp # Observer: counts events
│ │ ├── TimeDisplayService.hpp # Observer: formats time display
│ │ ├── App.hpp # Application orchestrator
│ │ ├── FreeRTOSConfig.h # FreeRTOS configuration
│ │ ├── main.h # HAL pin definitions
│ │ └── stm32f0xx_hal_conf.h # HAL module selection
│ ├── Src/
│ │ ├── Observable.cpp # Observable implementation
│ │ ├── TimerService.cpp # Timer publisher implementation
│ │ ├── CounterService.cpp # Counter observer implementation
│ │ ├── TimeDisplayService.cpp # Display observer implementation
│ │ ├── App.cpp # App init + task creation
│ │ ├── main.c # HAL init + App entry
│ │ ├── stm32f0xx_it.c # Interrupt handlers
│ │ └── system_stm32f0xx.c # System clock config
│ └── Startup/
│ └── startup_stm32f051c8tx.s # Vector table + reset handler
├── Drivers/
│ ├── CMSIS/ # ARM CMSIS headers
│ └── STM32F0xx_HAL_Driver/ # ST HAL library
├── Middlewares/
│ └── Third_Party/
│ └── FreeRTOS/ # FreeRTOS kernel
│ ├── Source/
│ │ ├── tasks.c
│ │ ├── queue.c
│ │ ├── timers.c
│ │ └── portable/
│ │ ├── GCC/ARM_CM0/ # Cortex-M0 port
│ │ └── MemMang/
│ │ └── heap_4.c # Memory scheme
│ └── Include/
├── STM32F051C8TX_FLASH.ld # Linker script (8KB RAM, 64KB Flash)
├── Makefile # Build system
└── .cproject / .project # STM32CubeIDE project files
Observable API Summary
Observable
| Method | Context | Description |
|---|
subscribe(observer*) | Task | Register observer (max 4) |
unsubscribe(observer*) | Task | Remove observer |
publish(const T&) | Task | Enqueue to normal queue |
publishHighPriority(const T&) | Task | Enqueue to high queue |
publishFromISR(const T&, BaseType_t*) | ISR | Enqueue from interrupt |
publishHighPriorityFromISR(const T&, BaseType_t*) | ISR | High-priority from ISR |
notify(const T&) | Dispatcher | Call all observer callbacks |
ObservableDispatcher
| Method | Description |
|---|
start(name, priority, stack, size, tcb) | Start dispatcher task |
enqueue(QueueItem&) | Add to normal queue |
enqueueHighPriority(QueueItem&) | Add to high queue |
hasQueueSpace(priority) | Check if queue has room |
getStats() | Get queue statistics |
setErrorCallback(cb, ctx) | Set error handler |
Tech Stack Reference
| Technology | Version | Purpose |
|---|
| STM32F051C8 | Rev Z | Target MCU (Cortex-M0, 48MHz) |
| FreeRTOS | 10.4.6+ | Real-time operating system |
| C++14 | GCC 10.3+ | Application language standard |
| STM32CubeIDE | 1.13+ | IDE and project management |
| STM32 HAL | 1.11.x | Hardware abstraction layer |
| ARM CMSIS | 5.x | Cortex Microcontroller Software Interface |
| GNU ARM Toolchain | 10.3+ | Cross-compiler (arm-none-eabi-gcc) |
| OpenOCD / ST-Link | Latest | Debug and flash programming |
Compiler Flags
-mcpu=cortex-m0 -mthumb -mfloat-abi=soft
-std=c++14 -fno-exceptions -fno-rtti -fno-threadsafe-statics
-Os -ffunction-sections -fdata-sections
-Wall -Wextra -Werror
Linker Flags
-Wl,--gc-sections -Wl,-Map=output.map
-T STM32F051C8TX_FLASH.ld
--specs=nosys.specs --specs=nano.specs
Spec Gap Prediction System
When implementing new services from incomplete specifications, PROACTIVELY predict missing requirements:
New Service Prediction Matrix
When a spec mentions a new "Sensor Service", predict ALL required components:
| Component | Predicted Items | Status |
|---|
| Model | SensorModel struct in Models.hpp | Check |
| Service class | SensorService.hpp + .cpp | Check |
| Observer | Observer callback + registration | Check |
| Task | FreeRTOS task with static stack | Check |
| ISR (if hardware) | *FromISR() publish variant | Check |
| Error handling | Queue overflow handler | Check |
| Memory impact | RAM/Flash delta calculation | Check |
Memory Impact Prediction
For every new component, predict RAM/Flash cost:
New Model Type:
+ sizeof(Model) * queue_sizes (high + normal) for queue storage
+ sizeof(QueueItem) if union grows
+ Model definition in Flash (~20 bytes .rodata)
Predicted: +96 to +192 bytes RAM
New Observer:
+ 8 bytes (callback + context pointer)
+ Observer struct storage (~8 bytes)
Predicted: +16 bytes RAM
New Task:
+ Stack size (128 words = 512 bytes typical)
+ TCB (88 bytes)
+ Task code in Flash (~200-500 bytes)
Predicted: +600 bytes RAM, +400 bytes Flash
New Service Class:
+ Member variables (varies)
+ Code in Flash (~500-2000 bytes)
Predicted: +20-100 bytes RAM, +1000 bytes Flash
Ask Clarification Prompt
When specs are incomplete for embedded, ASK before implementing:
The specification mentions "Add temperature monitoring" but doesn't specify:
1. What I2C sensor? (SHT31, BME280, LM75, etc.)
2. Polling interval? (100ms vs 1s has major CPU impact)
3. Should readings publish via normal or high-priority queue?
4. Is ISR-based reading needed (DMA) or blocking I2C OK?
5. How many temperature thresholds/alarms?
6. What is the acceptable RAM budget for this feature?
Please clarify before I proceed with implementation.
Peripheral Integration Patterns
Adding a New Peripheral (Step by Step)
Step 1: Configure in STM32CubeMX (.ioc file)
- Enable peripheral (UART, I2C, SPI, TIM, ADC)
- Configure pins, clock, DMA if needed
- Generate code (HAL init functions)
Step 2: Create Model
- Add struct to Models.hpp
- Add static_assert for size and trivially_copyable
- Add to ModelType enum
- Add to QueueItem union
- Verify QueueItem size still fits
Step 3: Create Service
- Header: callback, init, task entry (if needed)
- Implementation: init, taskLoop, publish logic
- Follow existing TimerService/CounterService pattern
Step 4: Register in App
- Add Observable<NewModel> member
- Add Service member
- Add Observer member
- Wire in App::init()
- Create task in App::createTasks() if needed
Step 5: Verify Memory
- Build and check arm-none-eabi-size
- Verify RAM < 75%, Flash < 90%
- Update memory budget table
HAL Callback to Observable Bridge Pattern
extern Observable<SensorModel> sensorObservable;
void HAL_I2C_MasterRxCpltCallback(I2C_HandleTypeDef* hi2c) {
if (hi2c->Instance == I2C1) {
SensorModel model;
model.temperature = parseTemperature(rxBuffer);
model.humidity = parseHumidity(rxBuffer);
model.status = 0;
BaseType_t woken = pdFALSE;
sensorObservable.publishFromISR(model, &woken);
portYIELD_FROM_ISR(woken);
}
}
Debug and Troubleshooting
Hard Fault Debugging
void HardFault_Handler(void) {
volatile uint32_t* CFSR = (volatile uint32_t*)0xE000ED28;
volatile uint32_t* HFSR = (volatile uint32_t*)0xE000ED2C;
volatile uint32_t* MMFAR = (volatile uint32_t*)0xE000ED34;
volatile uint32_t* BFAR = (volatile uint32_t*)0xE000ED38;
volatile uint32_t cfsr = *CFSR;
volatile uint32_t hfsr = *HFSR;
volatile uint32_t mmfar = *MMFAR;
volatile uint32_t bfar = *BFAR;
(void)cfsr; (void)hfsr; (void)mmfar; (void)bfar;
__BKPT(0);
while (1) {}
}
Stack Overflow Debug Pattern
extern "C" void vApplicationStackOverflowHook(
TaskHandle_t xTask, char* pcTaskName
) {
volatile char* taskName = pcTaskName;
(void)taskName;
__BKPT(0);
while (1) {}
}
Runtime Statistics (Debug Build Only)
#ifdef DEBUG
struct RuntimeStats {
volatile uint32_t maxDispatchTimeUs;
volatile uint32_t avgDispatchTimeUs;
volatile uint32_t totalEvents;
volatile uint32_t maxQueueDepth;
};
static RuntimeStats stats = {};
uint32_t start = DWT->CYCCNT;
dispatch(item);
uint32_t elapsed = DWT->CYCCNT - start;
uint32_t elapsedUs = elapsed / (SystemCoreClock / 1000000);
if (elapsedUs > stats.maxDispatchTimeUs) {
stats.maxDispatchTimeUs = elapsedUs;
}
stats.totalEvents++;
#endif
Architecture Rating: 9.1/10
Strengths
- Zero-copy model passing minimizes RAM usage
- Dual-priority queuing enables real-time responsiveness
- Static allocation eliminates heap fragmentation
- ISR-safe API prevents hard faults
- Type-safe C++14 templates catch errors at compile time
- 53.2% RAM usage leaves healthy headroom
Known Limitations
- Fixed 4-observer maximum per Observable
- Single dispatcher task (shared across all Observables)
- No per-observer filtering (all observers get all events)
- Lost events on queue overflow (no retry/backpressure)
- Fixed queue sizes (cannot resize at runtime)
- C++ only (no pure C API)
