feat: support headless LILYGO T-Embed CC1101 Plus

Configure the integrated radio power, shared SPI selects, RF path and fixed wiring without changing generic boards. Preload output latches for Arduino 3 and publish radio availability only after register and RX checks succeed. Reuse the existing partition table and protect integrated, USB and PSRAM pins across configuration and GPIO output paths.

Exercise production setup, RX and queue admission methods in a hardware-boundary host harness, run it in CI and document the opt-in build. Keep restore policy, security corrections and release tooling outside this board-only change.
This commit is contained in:
R. Sid Shaytay 2026-11-06 01:19:31 -08:00
parent e873dc8309
commit fdf840a236
22 changed files with 715 additions and 31 deletions

70
src/BoardProfile.cpp Normal file
View file

@ -0,0 +1,70 @@
#include "BoardProfile.h"
#include <SPI.h>
#if defined(ESPSOMFY_LILYGO_T_EMBED_CC1101_PLUS)
#include <driver/gpio.h>
#endif
namespace BoardProfile {
#if defined(ESPSOMFY_LILYGO_T_EMBED_CC1101_PLUS)
static bool initialized = false;
static void output(uint8_t pin, uint8_t level) {
// Arduino 3 rejects digitalWrite before GPIO ownership is established.
// Preload the hardware latch so active-low selects do not pulse on enable.
gpio_set_level(static_cast<gpio_num_t>(pin), level);
pinMode(pin, OUTPUT);
}
void begin() {
if(initialized) return;
// Deselect every shared-SPI slave before enabling its power rail.
// https://github.com/Xinyuan-LilyGO/T-Embed-CC1101/blob/c36826e0f91311cb591c4545fccf91e254fc55dc/examples/cc1101_recv_irq/cc1101_recv_irq.ino
output(displayCS, HIGH);
output(sdCS, HIGH);
output(nrfCS, HIGH);
output(cs, HIGH);
output(nrfCE, LOW);
output(backlight, LOW);
output(sw1, HIGH);
output(sw0, HIGH);
output(power, HIGH);
delay(10); // Conservative rail settling; no peripheral drivers are started.
initialized = true;
}
bool prepareRadio(float frequency) {
begin();
// This hardware profile selects only the 433 MHz RF filter path.
if(!(frequency >= 387.0f && frequency <= 464.0f)) {
Serial.println("Radio disabled: frequency is outside the selected 433 MHz band");
return false;
}
// Arduino 3 owns these pads while SPI is active. Release that ownership
// before the GPIO readiness probe, including when reapplying settings.
SPI.end();
pinMode(miso, INPUT);
output(sck, LOW);
output(mosi, LOW);
digitalWrite(cs, LOW);
unsigned long started = millis();
while(digitalRead(miso) == HIGH && millis() - started < 20) delay(1);
bool ready = digitalRead(miso) == LOW;
digitalWrite(cs, HIGH);
if(!ready) Serial.println("CC1101 not ready: MISO stayed HIGH; check power/shared SPI before retrying");
if(ready) SPI.begin(sck, miso, mosi, cs);
return ready;
}
bool usesPin(uint8_t pin) {
// USB CDC and in-package flash/OPI PSRAM must never become relay outputs.
return pin == 19 || pin == 20 || (pin >= 26 && pin <= 37) ||
pin == power || pin == sck || pin == mosi || pin == miso ||
pin == cs || pin == tx || pin == rx || pin == sw1 || pin == sw0 ||
pin == displayCS || pin == sdCS || pin == nrfCS || pin == nrfCE || pin == backlight;
}
#else
void begin() {}
bool prepareRadio(float) { return true; }
bool usesPin(uint8_t) { return false; }
#endif
}

33
src/BoardProfile.h Normal file
View file

@ -0,0 +1,33 @@
#pragma once
#include <Arduino.h>
namespace BoardProfile {
#if defined(ESPSOMFY_LILYGO_T_EMBED_CC1101_PLUS)
#if !defined(CONFIG_IDF_TARGET_ESP32S3)
#error "The LILYGO T-Embed CC1101 Plus profile requires an ESP32-S3 target"
#endif
constexpr bool integratedRadio = true;
#else
constexpr bool integratedRadio = false;
#endif
// LILYGO T-Embed CC1101 Plus integrated hardware; not the non-Plus board.
constexpr uint8_t power = 15;
constexpr uint8_t sck = 11;
constexpr uint8_t mosi = 9;
constexpr uint8_t miso = 10;
constexpr uint8_t cs = 12;
constexpr uint8_t tx = 3;
constexpr uint8_t rx = 38;
constexpr uint8_t sw1 = 47;
constexpr uint8_t sw0 = 48;
constexpr uint8_t displayCS = 41;
constexpr uint8_t sdCS = 13;
constexpr uint8_t nrfCS = 44;
constexpr uint8_t nrfCE = 43;
constexpr uint8_t backlight = 21;
void begin();
bool prepareRadio(float frequency);
bool usesPin(uint8_t pin);
}

View file

@ -6,6 +6,7 @@
#include "Utils.h"
#include "ConfigSettings.h"
#include "RollingCode.h"
#include "BoardProfile.h"
static const char *TAG = "ConfigFile";
@ -288,10 +289,10 @@ void ShadeConfigFile::readShade(SomfyShade *shade) {
shade->gpioFlags = rec.gpioFlags;
shade->roomId = rec.roomId;
if(shade->proto == radio_proto::GP_Relay || shade->proto == radio_proto::GP_Remote) {
pinMode(shade->gpioUp, OUTPUT);
pinMode(shade->gpioDown, OUTPUT);
if(!BoardProfile::usesPin(shade->gpioUp)) pinMode(shade->gpioUp, OUTPUT);
if(!BoardProfile::usesPin(shade->gpioDown)) pinMode(shade->gpioDown, OUTPUT);
}
if(shade->proto == radio_proto::GP_Remote)
if(shade->proto == radio_proto::GP_Remote && !BoardProfile::usesPin(shade->gpioMy))
pinMode(shade->gpioMy, OUTPUT);
}
void ShadeConfigFile::readGroup(SomfyGroup *group) {

View file

@ -1,9 +1,19 @@
#include "esp_log.h"
#include "Somfy.h"
#include "BoardProfile.h"
static const char *TAG = "Somfy";
// A backup may contain GPIO assignments from another board. Keep its shade
// identity, but never drive a pad used by this board's integrated hardware.
static bool usesBoardGPIOs(const SomfyShade &shade) {
if(shade.proto != radio_proto::GP_Relay && shade.proto != radio_proto::GP_Remote) return false;
return BoardProfile::usesPin(shade.gpioUp) || BoardProfile::usesPin(shade.gpioDown) ||
(shade.proto == radio_proto::GP_Remote && BoardProfile::usesPin(shade.gpioMy));
}
void SomfyShade::setGPIOs() {
if(usesBoardGPIOs(*this)) return;
if(this->proto == radio_proto::GP_Relay) {
// Determine whether the direction needs to be set.
uint8_t p_on = (this->gpioFlags & (uint8_t)gpio_flags_t::LowLevelTrigger) == 0x00 ? HIGH : LOW;
@ -65,6 +75,7 @@ void SomfyShade::setGPIOs() {
}
void SomfyRemote::triggerGPIOs(somfy_frame_t &frame) { }
void SomfyShade::triggerGPIOs(somfy_frame_t &frame) {
if(usesBoardGPIOs(*this)) return;
if(this->proto == radio_proto::GP_Remote) {
uint8_t p_on = (this->gpioFlags & (uint8_t)gpio_flags_t::LowLevelTrigger) == 0x00 ? HIGH : LOW;
uint8_t p_off = (this->gpioFlags & (uint8_t)gpio_flags_t::LowLevelTrigger) == 0x00 ? LOW : HIGH;

View file

@ -20,6 +20,7 @@
#include "esp_rom_sys.h"
#include <inttypes.h>
#include "Timing.h"
#include "BoardProfile.h"
static const char *TAG = "Main";
#define LOOP_SLOW_MS 100
@ -79,6 +80,7 @@ static void onAllocFailed(size_t size, uint32_t caps, const char *function) {
void setup() {
Serial.begin(SERIAL_BAUD);
BoardProfile::begin();
heap_caps_register_failed_alloc_callback(onAllocFailed);
ESP_LOGI(TAG, "Startup/Boot....");
esp_core_dump_summary_t summary;

View file

@ -52,8 +52,7 @@ int8_t SomfyShade::validateJSON(JsonObject &obj) {
const uint8_t downPin = !obj["gpioDown"].isNull() ? obj["gpioDown"].as<uint8_t>() : this->gpioDown;
const uint8_t myPin = !obj["gpioMy"].isNull() ? obj["gpioMy"].as<uint8_t>() : this->gpioMy;
pin_users_t radio, ethernet, others;
if(somfy.transceiver.config.enabled)
radio.uses = [](uint8_t pin, void *) { return somfy.transceiver.usesPin(pin); };
radio.uses = [](uint8_t pin, void *) { return somfy.transceiver.usesPin(pin); };
#if HAS_ETHERNET
if(settings.connType == conn_types_t::ethernet || settings.connType == conn_types_t::ethernetpref)
ethernet.uses = [](uint8_t pin, void *) { return settings.Ethernet.usesPin(pin); };
@ -158,12 +157,12 @@ int8_t SomfyShade::fromJSON(JsonObject &obj) {
if(this->proto == radio_proto::GP_Remote || this->proto == radio_proto::GP_Relay) {
if(!obj["gpioUp"].isNull()) this->gpioUp = obj["gpioUp"];
if(!obj["gpioDown"].isNull()) this->gpioDown = obj["gpioDown"];
pinMode(this->gpioUp, OUTPUT);
pinMode(this->gpioDown, OUTPUT);
if(!BoardProfile::usesPin(this->gpioUp)) pinMode(this->gpioUp, OUTPUT);
if(!BoardProfile::usesPin(this->gpioDown)) pinMode(this->gpioDown, OUTPUT);
}
if(this->proto == radio_proto::GP_Remote) {
if(!obj["gpioMy"].isNull()) this->gpioMy = obj["gpioMy"];
pinMode(this->gpioMy, OUTPUT);
if(!BoardProfile::usesPin(this->gpioMy)) pinMode(this->gpioMy, OUTPUT);
}
}
return err;

View file

@ -101,7 +101,7 @@ bool somfy_rx_queue_t::pop(somfy_rx_t *rx) {
return false;
}
void Transceiver::sendFrame(byte *frame, uint8_t sync, uint8_t bitLength) {
if(!this->config.enabled) return;
if(!this->available()) return;
uint32_t pin = 1 << this->config.TXPin;
if (sync == 2 || sync == 12) { // Only with the first frame. Repeats do not get a wakeup pulse.
// All information online for the wakeup pulse appears to be incorrect. While there is a wakeup
@ -252,9 +252,9 @@ static std::atomic<bool> scanEmitPending{false};
void Transceiver::beginFrequencyScan() {
// The scan retunes the radio so nothing may transmit until it ends. This
// also aborts a transmission in flight so the lock below is never held long.
if(this->config.enabled) this->suspendTx(TX_SUSPEND_SCAN);
if(this->available()) this->suspendTx(TX_SUSPEND_SCAN);
RadioLock lock(portMAX_DELAY, true);
if(this->config.enabled) {
if(this->available()) {
this->disableReceive();
rxmode = 3;
scanStart = millis();
@ -272,7 +272,7 @@ void Transceiver::beginFrequencyScan() {
}
void Transceiver::processFrequencyScan(bool received) {
RadioLock lock;
if(this->config.enabled && rxmode == 3) {
if(this->available() && rxmode == 3) {
if(received) {
currRSSI = ELECHOUSE_cc1101.getRssi();
if((long)(markFreq * 100) == (long)(currFreq * 100)) {
@ -365,22 +365,41 @@ void Transceiver::emitFrame(somfy_frame_t *frame, somfy_rx_t *rx) {
void Transceiver::clearReceived(void) {
//packet_received = false;
//memset(receive_buffer, 0x00, sizeof(receive_buffer));
if(this->config.enabled)
if(this->available())
//attachInterrupt(interruptPin, handleReceive, FALLING);
attachInterrupt(interruptPin, handleReceive, CHANGE);
}
void Transceiver::enableReceive(void) {
if(this->available()) this->startReceive();
}
bool Transceiver::startReceive() {
uint32_t timing = millis();
if(rxmode > 0) return;
if(this->config.enabled) {
rxmode = 1;
pinMode(this->config.RXPin, INPUT);
interruptPin = digitalPinToInterrupt(this->config.RXPin);
ELECHOUSE_cc1101.SetRx();
//attachInterrupt(interruptPin, handleReceive, FALLING);
attachInterrupt(interruptPin, handleReceive, CHANGE);
ESP_LOGD(TAG, "Enabled receive on Pin #%d Timing: %ld", this->config.RXPin, millis() - timing);
if(rxmode > 0) return true;
rxmode = 1;
pinMode(this->config.RXPin, INPUT);
interruptPin = digitalPinToInterrupt(this->config.RXPin);
ELECHOUSE_cc1101.SetRx();
if(BoardProfile::integratedRadio) {
uint8_t state;
do {
delay(1);
state = ELECHOUSE_cc1101.SpiReadStatus(CC1101_MARCSTATE) & 0x1F;
} while(state != 0x0D && millis() - timing < 20);
Serial.printf("CC1101 MARCSTATE=0x%02X (RX=0x0D); RF switch readback SW1=%d SW0=%d\n",
state, digitalRead(BoardProfile::sw1), digitalRead(BoardProfile::sw0));
if(state != 0x0D) {
Serial.println("CC1101 failed to enter RX; radio unavailable");
ELECHOUSE_cc1101.setSidle();
this->config.radioInit = false;
this->_available = false;
rxmode = 0;
return false;
}
}
//attachInterrupt(interruptPin, handleReceive, FALLING);
attachInterrupt(interruptPin, handleReceive, CHANGE);
ESP_LOGD(TAG, "Enabled receive on Pin #%d Timing: %ld", this->config.RXPin, millis() - timing);
return true;
}
void Transceiver::disableReceive(void) {
rxmode = 0;
@ -396,12 +415,15 @@ void Transceiver::setConfig(const transceiver_config_t &cfg) {
// Saving first means a radio that locks up while applying comes back with
// the new config after the reboot.
RadioLock lock(portMAX_DELAY, true);
if(this->config.enabled && this->config.TXPin != cfg.TXPin) pinMode(this->config.TXPin, INPUT);
this->config = cfg;
transceiver_config_t next = cfg;
next.applyBoardPins();
if(this->config.enabled && this->config.TXPin != next.TXPin) pinMode(this->config.TXPin, INPUT);
this->config = next;
this->config.save();
this->config.apply();
}
bool Transceiver::usesPin(uint8_t pin) {
if(BoardProfile::usesPin(pin)) return true;
if(this->config.enabled) {
if(this->config.SCKPin == pin ||
this->config.TXPin == pin ||
@ -575,10 +597,41 @@ void transceiver_config_t::load() {
pref.end();
//this->printBuffer = somfy.transceiver.printBuffer;
}
void transceiver_config_t::applyBoardPins() {
if(!BoardProfile::integratedRadio) return;
this->SCKPin = BoardProfile::sck;
this->MOSIPin = BoardProfile::mosi;
this->MISOPin = BoardProfile::miso;
this->CSNPin = BoardProfile::cs;
this->TXPin = BoardProfile::tx;
this->RXPin = BoardProfile::rx;
}
static void warnBootPin(const char *name, uint8_t pin) {
const char *effect = bootPinEffect(pin);
if(effect) ESP_LOGW(TAG, "Radio %s is on GPIO%u, a strapping pin the radio can drive at reset. %s", name, pin, effect);
}
static bool checkBoardRadio(float frequency) {
if(!BoardProfile::integratedRadio) return true;
uint8_t part = ELECHOUSE_cc1101.SpiReadStatus(CC1101_PARTNUM);
uint8_t version = ELECHOUSE_cc1101.SpiReadStatus(CC1101_VERSION);
uint8_t gdo0 = ELECHOUSE_cc1101.SpiReadReg(CC1101_IOCFG0);
uint8_t gdo2 = ELECHOUSE_cc1101.SpiReadReg(CC1101_IOCFG2);
uint8_t packet = ELECHOUSE_cc1101.SpiReadReg(CC1101_PKTCTRL0);
uint8_t modem = ELECHOUSE_cc1101.SpiReadReg(CC1101_MDMCFG2);
uint32_t word = (static_cast<uint32_t>(ELECHOUSE_cc1101.SpiReadReg(CC1101_FREQ2)) << 16) |
(static_cast<uint32_t>(ELECHOUSE_cc1101.SpiReadReg(CC1101_FREQ1)) << 8) |
ELECHOUSE_cc1101.SpiReadReg(CC1101_FREQ0);
float actual = word * (26.0f / 65536.0f);
Serial.printf("CC1101 PARTNUM=0x%02X VERSION=0x%02X IOCFG0=0x%02X IOCFG2=0x%02X PKTCTRL0=0x%02X MDMCFG2=0x%02X\n",
part, version, gdo0, gdo2, packet, modem);
Serial.printf("CC1101 frequency requested=%.3f readback=%.3f MHz; GDO0 TX=%u GDO2 RX=%u\n",
frequency, actual, BoardProfile::tx, BoardProfile::rx);
return part == 0 && version != 0 && version != 0xFF &&
gdo0 == 0x0D && gdo2 == 0x0D && (packet & 0x30) == 0x30 &&
(modem & 0x70) == 0x30 && actual > frequency - 0.01f && actual < frequency + 0.01f;
}
void transceiver_config_t::apply() {
Preferences pref;
// A transmission in flight stops after its current frame so the radio can
@ -588,12 +641,18 @@ void transceiver_config_t::apply() {
// Reconfiguring the radio ends a frequency scan so TX may resume.
const bool wasScanning = rxmode == 3;
somfy.transceiver.disableReceive();
// Generic radios retain their enabled-based availability. The integrated
// radio is published ready only after its register/RX checks succeed.
somfy.transceiver._available = false;
if(wasScanning) {
somfy.transceiver.resumeTx(TX_SUSPEND_SCAN);
scanEmitPending = true;
}
this->applyBoardPins();
radioBitLength = this->type;
if(this->enabled) {
this->radioInit = false;
if(!BoardProfile::prepareRadio(this->frequency)) return;
bool radioInit = true;
pref.begin("CC1101");
radioInit = pref.getBool("radioInit", true);
@ -655,14 +714,17 @@ void transceiver_config_t::apply() {
// 3 = Address check and 0 (0x00) and 255 (0xFF) broadcast.
if (!ELECHOUSE_cc1101.getCC1101()) {
const bool detected = ELECHOUSE_cc1101.getCC1101();
// Always collect the integrated board readback, even if detection fails.
const bool boardRadioValid = checkBoardRadio(this->frequency);
if (!detected || !boardRadioValid) {
ESP_LOGE(TAG, "Error setting up the radio");
this->radioInit = false;
}
else {
ESP_LOGI(TAG, "Successfully set up the radio");
somfy.transceiver.enableReceive();
this->radioInit = true;
this->radioInit = somfy.transceiver.startReceive();
somfy.transceiver._available = this->radioInit;
}
pref.begin("CC1101");
pref.putBool("radioInit", true);
@ -765,6 +827,9 @@ uint32_t Transceiver::submitTx(somfy_tx_job_t &job, bool priority, uint16_t dela
ESP_LOGE(TAG, "Radio task not started, dropping transmission");
return 0;
}
// Read published readiness without waiting behind a transmission. A queued
// job checks it again under the radio lock immediately before sending.
if(BoardProfile::integratedRadio && !this->available()) return 0;
uint32_t ticket;
{
TxQueueLock lock;
@ -838,7 +903,7 @@ void Transceiver::runJob(somfy_tx_job_t &job) {
start = this->sched.start(job.ticket, millis());
}
if(!start) return;
const bool complete = this->transmitJob(job);
const bool complete = (!BoardProfile::integratedRadio || this->available()) && this->transmitJob(job);
TxQueueLock qlock;
this->sched.ended(job.ticket, complete, millis());
}
@ -872,7 +937,7 @@ void Transceiver::startTxTask() {
}
somfy_frame_t& Transceiver::lastFrame() { return this->frame; }
void Transceiver::beginTransmit() {
if(this->config.enabled) {
if(this->available()) {
this->disableReceive();
pinMode(this->config.TXPin, OUTPUT);
digitalWrite(this->config.TXPin, 0);
@ -880,7 +945,7 @@ void Transceiver::beginTransmit() {
}
}
void Transceiver::endTransmit() {
if(this->config.enabled) {
if(this->available()) {
ELECHOUSE_cc1101.setSidle();
//delay(100);
this->enableReceive();

View file

@ -1,12 +1,14 @@
#ifndef TRANSCEIVER_H
#define TRANSCEIVER_H
#include <Arduino.h>
#include <atomic>
#include <Preferences.h>
#include <ArduinoJson.h>
#include "SomfyFrame.h"
#include "TxBuffer.h"
#include "RadioScheduler.h"
#include "PulseDecoder.h"
#include "BoardProfile.h"
// The CC1101 radio: receive decoding, the radio task that transmits radio
// jobs, the frequency scan and the radio config.
@ -25,7 +27,7 @@ struct somfy_rx_queue_t {
};
struct transceiver_config_t {
bool printBuffer = false;
bool enabled = false;
bool enabled = BoardProfile::integratedRadio;
uint8_t type = 56; // 56 or 80 bit protocol.
radio_proto proto = radio_proto::RTS;
uint8_t SCKPin = 18;
@ -44,11 +46,15 @@ struct transceiver_config_t {
void save();
void load();
void apply();
void applyBoardPins();
// Removes a key no longer used from the open CC1101 namespace.
void removeNVSKey(Preferences &pref, const char *key);
};
class Transceiver {
private:
friend struct transceiver_config_t;
// Published under the radio lock; queue producers never wait on SPI.
std::atomic<bool> _available{false};
static void handleReceive();
static void txTask(void *arg);
bool _received = false;
@ -56,11 +62,13 @@ class Transceiver {
// Only touched under the TX queue lock.
RadioScheduler sched;
void startTxTask();
bool startReceive();
bool transmitJob(somfy_tx_job_t &job);
// Sends a job taken off the queue and leaves a frame beat after it.
void runJob(somfy_tx_job_t &job);
public:
transceiver_config_t config;
bool available() const { return BoardProfile::integratedRadio ? _available.load() : this->config.enabled; }
bool printBuffer = false;
bool fromJSON(JsonObject& obj);
// Swaps in, saves and applies the config.