R7FS7MOD

Lumeward

Firmware for an autonomous sensor hub built into an ordinary motion-sensor luminaire. A 60 GHz FMCW radar, an infrared presence sensor, a precision barometer, an IMU, a microphone and a speaker sit behind the plastic of a two-euro solar lamp; a Cortex-M4 module at 240 MHz runs them, together with Wi-Fi, Bluetooth LE, LoRa, an SD card and a diagnostic web interface.

The name is the platform, not the product: lume for the light it still is, ward for what it now does. The first application on it is a door answering machine, and more are meant to follow as separate tasks in the same project.

Hardware at a glance

From the outside, Lumeward still looks like the ordinary solar motion-sensor lamp that provided its enclosure.

Electronics during assembly	Main controller installed in the enclosure

The hardware and how it came to exist are described in the article series this repository accompanies. The firmware is the bulk of what is here; the board files below are what it runs on.

Boards

Two boards make the device, the same 56.97 x 25.91 mm outline stacked one on the other. MODULE_R7FS7v2 carries the MCU, the memories and every radio; RADADPTR01 is the carrier it plugs into, and brings out the LED drivers, the radar and the sensor buses. Both are KiCad projects under docs/:

The renders below are exported from those projects: every layer except solder mask and paste, on the PCB editor's own colours. Each image links to the full-resolution PNG - the schematic sheets are A3 at 400 dpi, where the smallest lettering still reads.

MODULE_R7FS7v2

Sheet 1 - the S7G2 and its pinout	Sheet 2 - power, charger, RTC, ADCs, USB
Sheet 3 - SDRAM, SD card, NOR flash, Wi-Fi, LoRa, codec, IMU	Sheet 4 - the three board-to-board connectors

RADADPTR01

Board, all layers	Schematic

Repository layout

CMakeLists.txt / CMakePresets.json  the LLVM/CMake build graph and Debug/Release presets
BootLoader/                        the bootloader over the same framework_src
src/                               the application layer
framework_src/                     the platform layer, shared by future applications
  MODULE_R7FS7v2/                  the hardware layer and the platform header with its two faces
  ThreadX/ NetXDuo/ UsbX/          Eclipse ThreadX components, MIT
  CMSIS/                           the ARM compiler-abstraction and DSP headers, Apache-2.0
  Vendor_libs/                     prebuilt archives the firmware links (SCE crypto, CMSIS-DSP)
  Libraries_LLVM/                  committed clang archives for builds without the closed SDK sources
Tools/LLVM/                        LLVM build, packaging, memory-report and J-Link scripts
Tools/Build/                       shared versioning, packaging and factory-image scripts
  demo_keys/                       the published demo key set the packer signs with when there is no other
Tools/Manual/                      scripts run by hand: delivery to the module, uploads, the bench
WebDevLink/                        browser diagnostic client, one panel per subsystem
SD_card/                           what the card carries: prompts and service tones
ParametersGenerator/               the parameter database and its generator
AndroidDevLink/                    Android client for the same diagnostic protocol
docs/                              build notes, the update key, and the hardware
  *_PCB_KiCad/                     KiCad projects of the two boards
  *_Schematic_PNG/                 schematic sheets and board renders exported from them

The split between src/ and framework_src/ is the point of the project. Everything in framework_src/ is application-independent: RTOS, file system, networking, USB, audio, the parameter store, the logger, the DevLink diagnostic protocol, the web server and the cloud client. Everything specific to answering the door lives in src/.

The application layer

Building

The supported build uses Arm Toolchain for Embedded 22.1.0 (LLVM/clang), CMake 3.28 or newer, Ninja 1.11 or newer, sccache, and Python 3.10 or newer with cryptography. SEGGER J-Link Software is needed only for flashing and debugging. The installation paths, download checksums and debugger setup are in docs/LLVM_Build.md.

A fresh clone builds as it is. Two source trees may not be republished - the Renesas SSP and the Azure RTOS FileX build with exFAT - so they are not part of this repository, and everything that needs their headers is committed as an archive instead:

The rest - the application, the kernel, the network stack, USB, the diagnostic protocol - compiles from source. framework_src/MODULE_R7FS7v2/MODULE_R7FS7v2.h is the platform header every source includes; it has two faces, Platform_full.h for a machine that has the SDK and Platform_api.h for one without, chosen automatically by whether bsp_api.h can be found. The two faces define identical structure layouts, which is what lets the archives and the sources link. CMake detects whether the closed SDK trees are present. A public clone automatically links the matching Debug or Release archives from framework_src/Libraries_LLVM/; no separate preparation step is required.

From VS Code, Terminal -> Run Build Task offers LLVM: Build Lumeward, LLVM: Build Bootloader, LLVM: Build All (app + bootloader + factory) and the matching J-Link flash tasks. From PowerShell, build all images with:

powershell -NoProfile -ExecutionPolicy Bypass -File Tools/LLVM/Build.ps1 `
  -Configuration Debug -Target all

powershell -NoProfile -ExecutionPolicy Bypass -File Tools/LLVM/Build.ps1 `
  -Configuration Release -Target all

For direct CMake use, the equivalent presets are llvm-debug and llvm-release:

C:\DevTools\cmake\bin\cmake.exe --preset llvm-debug
C:\DevTools\cmake\bin\cmake.exe --build --preset llvm-debug

Build products are written to Out/Lumeward_LLVM/Debug or Out/Lumeward_LLVM/Release. Each directory contains the application and bootloader ELF, MAP, BIN and HEX files, the signed SD-card update images, and Lumeward_factory.hex.

On Windows, clone into a short path such as D:/Lumeward, or enable git config --global core.longpaths true first: some NetX Duo paths under addons/azure_iot/azure-sdk-for-c/ break checkout inside a deep directory.

The bootloader

BootLoader/ holds the other image in flash. The first 512 KB (0x00000000..0x0007FFFF) belong to the bootloader; the application starts at 0x00080000. At every reset the bootloader looks for firmware.bin in the root of the card, checks its signature, its CRC and its start address, writes it into the application region, renames it firmware.flashed, and restarts into the application when the region holds a valid image. A wake-up from deep software standby goes straight to the application. With no valid image it stays and blinks: green when the card is readable, red when it is not.

It is the same platform built with BOOTLOADER defined. BootLoader/src/ carries only the boot flow, the early hardware initialisation and a logger stub; everything else comes from framework_src/, where the bootloader-specific branches are marked #ifdef BOOTLOADER. The sources that need the closed headers are listed in BootLoader/Bootloader_bound_sources.txt and committed as libboot_bound_lib.a under framework_src/Libraries_LLVM/. The CMake build selects the archive automatically when those headers are unavailable.

powershell -NoProfile -ExecutionPolicy Bypass -File Tools/LLVM/Build.ps1 `
  -Configuration Debug -Target lumeward_bootloader

powershell -NoProfile -ExecutionPolicy Bypass -File Tools/LLVM/Build.ps1 `
  -Configuration Debug -Target lumeward_factory

The bootloader update is written to Out/Lumeward_LLVM/Debug/SD_card_bootloader_update_for_Lumeward/bootldr.bin, and the combined factory image to Out/Lumeward_LLVM/Debug/Lumeward_factory.hex; replace Debug with Release for a Release build. Lumeward_factory.hex is what a blank module gets over J-Link. Build and flash it from VS Code with LLVM: Flash Factory (app + bootloader), or from PowerShell:

powershell -NoProfile -ExecutionPolicy Bypass -File Tools/LLVM/Build.ps1 `
  -Configuration Debug -Target lumeward_factory -Flash Factory

A module that already runs the bootloader takes new firmware from the card, and takes a new bootloader the same way: bootldr.bin in the card root and the FLASH_BOOTLOADER command from DevLink.

Keys

The project ships a demo key set and nothing else. Tools/Build/demo_keys/ holds a signing key and a wrapping key whose private halves are published right there, and framework_src/Keys/Keys.c holds the public half of that signing key. A clone therefore builds every image, the signed ones included - firmware.bin, bootldr.bin, the versioned image and the update package - and the bootloader built from the same tree accepts them.

The demo keys protect nothing. Anyone can sign an image that a bootloader built with the demo Keys.c accepts, so they belong on a bench board. The build says so in its output every time it signs with them, and stops using them as soon as secrets/ exists or LUMEWARD_SIGNING_KEY and LUMEWARD_AES_KEY point at keys of your own. Issue those before a board leaves your hands.

The demo set carries no wrapped-key bundle: producing one needs a UFPK of your own and Renesas' key wrap service (docs/Wrapped_Key.md). A board with no bundle installed refuses every update image, demo-signed or not; the HEX images still flash over J-Link.

Two keys are involved, and they do different jobs:

Nothing that can forge an image is compiled into the firmware. The board holds the public half of the signing pair and a wrapped key that is worthless on any other chip, so reading out a board's flash yields neither the signing key nor the key to anyone else's images.

Tools/Build/firmware_packer.py is what signs and packs. It looks for the two keys in secrets/ beside the project root, or wherever LUMEWARD_SIGNING_KEY and LUMEWARD_AES_KEY point, and takes the demo set only when neither is there. Whichever key signs, it must be the one whose public half is in Keys.c: the packer compares them and stops on a mismatch, because a board would refuse that image anyway:

Generate your own pair, put its public half into Keys.c, and turn your AES key into the bundle with Renesas' Security Key Management Tool. docs/Wrapped_Key.md is the whole procedure, including the one-time key-wrap service exchange it needs. Back all three up somewhere that is not the build machine: losing the signing key means no further release can be signed, and losing the AES key means no release can be packed that a board already provisioned will read.

Two more secrets are compiled in and are demonstration values, not anything to keep: framework_src/MODULE_R7FS7v2/SoC_periphery/SDHI/s7_sdmmc_utils.c holds the SD card lock password the bootloader build uses, and the TLS credentials of the embedded web server are in framework_src/WEB_server/WEB_server_certificate.c. Rotate the password and regenerate the certificate pair with framework_src/Tools/cert_generator/ before anything faces a real network.

Provisioning a board

A board off the assembly line runs, but it is anonymous and it cannot be updated. Provisioning is what gives it an identity, its secrets and its update key, and it happens over DevLink from the Provisioning menu of WebDevLink/ while the board is on the USB cable. It is not optional: a board with no wrapped key refuses every update image outright, with no fallback.

Nothing is stored per board on the server side: every password is HKDF over one master secret salted with the chip UID, so a board always gets the same set and asking again is how a password is recovered rather than reset. The master secret never leaves the server and never reaches the browser page. The server itself is not part of this project - the panels expect one answering on http://localhost:8471, and you supply it.

Two more steps belong to the same bench pass, and both are one-way enough to be worth reading about first:

• The wrapped key, DL_APPCMD_INSTALL_KEY (0x1F). The bench sends the 108-byte bundle; the SCE7 engine rewraps it under a secret of that one chip and stores 52 bytes in DataFlash. The command answers only after re-probing what it wrote, and g_key_wrap_active is published in the DevLink TSA table, so a bench can confirm the key took rather than assume it.
• The debugger ID code, DL_APPCMD_SET_SWD_CODE (0x1E). Every board gets its own code, derived from the master secret and the chip UID; it goes straight into option memory and is never read back. Mode 1 - the debugger asks for the code but all-erase stays available - is what the panel offers, because it leaves a way back. Mode 3 locks the chip permanently and the firmware refuses it. If the code is lost, DL_WIPE_OP_UNLOCK_SWD releases the debugger with no programmer at all, as long as the application still runs and DevLink still answers.

Diagnostics

The device is meant to be tuned, not guessed at. WebDevLink/ is a browser client that speaks the DevLink protocol over serial, USB or the network and gives each subsystem its own panel: radar range profiles and a waterfall, infrared thresholds against live values, the audio level against its floor, the light arbiter with its active sources, and the answering machine with its current scenario step and recorder handshake.

Tools/Manual/door_answer_bench.py drives the same protocol from the command line: it delivers prompts to the card, runs a visit, pulls the recording back and analyses its spectrum. Batch reads give roughly 661 samples per second across a whole variable group, which is what makes a twenty-millisecond state visible at all.

Configuration

Parameters live in one database, ParametersGenerator/ParamsDB.txt, and the generator produces the C tables, the DevLink descriptors and the web schema from it in a single pass. Adding a parameter means adding a row, not touching four files.

Safety notice

This is a development project, not a certified product. The radar, the mains-free power path, the battery charger, the RF emissions and the recording of people at a door are all your responsibility to check against the rules that apply where you are. Recording visitors is regulated in most of Europe; the device is designed for a private entrance and stores nothing until someone stands at the door, but that does not make the recordings lawful everywhere.

Licence

The original work in this repository is licensed under the Apache License 2.0. See LICENSE for the terms and NOTICE for what the grant covers.

The licence covers this project's own code, not the third-party components shipped alongside it. Two of those are not open source at all and are present only as prebuilt archives, which is why THIRD_PARTY_NOTICES.md is worth reading before you reuse anything here in a product.