DALI C++ Library

A C++ implementation of the DALI stack used in lib/dali/*.dart. The portable DALI application layer mirrors Dart method names where practical, so it can become an embedded replacement target without starting that migration yet.

Portable Gateway Application Layer

include/dali_gateway.hpp is the hardware- and platform-independent gateway API. It uses only the C++17 standard library and deliberately owns neither a transceiver, a clock, a task, nor a platform storage API:

• DaliGatewayCache interprets direct, group, and broadcast forward frames; owns cached DALI state, persistence encoding, dirty tracking, and reconciliation work.
• DaliApplicationController implements the Part 103 logical application controller: standard control-device queries, IDENTIFY DEVICE, and control device short-address commissioning (INITIALISE, RANDOMISE, search, COMPARE, PROGRAM SHORT ADDRESS, VERIFY, and QUERY SHORT ADDRESS).
• The transport/adapter supplies the doubleSendConfirmed argument for commands that must be sent twice, sends returned backward frames, persists address state through registered key/value callbacks, and maps identifyRequested to its own physical indication.

This lets another IoT protocol use the DALI behavior without pulling in ESP-IDF. The current ESP-IDF gateway is one such adapter: its NVS wrapper and FreeRTOS/PHY timing stay under gateway/components/. Existing cloud and provisioning helpers remain compatibility integrations for the ESP-IDF component; they are not used by the portable gateway API.

For a non-ESP project, add this directory with CMake and link the focused dali_cpp_gateway target:

add_subdirectory(path/to/dali_cpp)
target_link_libraries(my_iot_adapter PRIVATE dali_cpp_gateway)

Bind a transceiver and an IoT protocol

The portable cache reports semantic status changes, so an adapter does not need to decode DALI opcodes before updating KNX, Modbus, BACnet, MQTT, or another IoT protocol:

DaliGatewayCache cache({
    true,   // cache enabled
    true,   // reconcile changes observed from another DALI master
    false,  // only reconcile the affected state category
    DaliGatewayCachePriorityMode::outsideBusFirst,
});

cache.setStatusUpdateCallback([](const DaliGatewayStatusUpdate& update) {
  // update.target is direct, group, or broadcast.
  // update.status contains the interpreted level/scene state.
  // update.affectedShortAddresses is ready for protocols that expose
  // per-device status.
  my_iot_adapter.publishDaliStatus(update);
});

cache.setPersistenceCallbacks({
    [](uint8_t channel, uint8_t address) {
      return my_storage.load(channel, address);
    },
    [](uint8_t channel, uint8_t address,
       const std::optional<std::string>& payload) {
      return my_storage.storeOrErase(channel, address, payload);
    },
    []() { return my_storage.commit(); },
});

cache.preloadChannel(0);

my_transceiver.onForwardFrame([&cache](uint8_t address, uint8_t data) {
  cache.observeForwardFrame(0, address, data,
                            DaliGatewayFrameOrigin::outsideBus);
});

// After a locally requested transmission succeeds, mirror it once. The cache
// performs all direct/group/broadcast and DTR-dependent interpretation.
if (my_transceiver.send(address, data)) {
  cache.mirrorForwardFrame(0, address, data);
}

// Call from the adapter's low-priority worker or shutdown path.
cache.flush();

The callbacks contain no ESP-IDF, RTOS, NVS, network, or transceiver types. An adapter chooses its own tasking, storage, bus timing, and IoT protocol.

The portable implementation is deliberately split by responsibility:

• dali_protocol.cpp decodes DALI target addressing.
• dali_gateway_cache.cpp owns cache state and adapter-facing persistence snapshots.
• dali_gateway_cache_mutation.cpp applies direct, group, broadcast, scene, DTR, and settings feedback.
• dali_gateway_reconciliation.cpp derives external-bus reconciliation work.
• dali_application_controller.cpp implements Part 103 control-device queries, commissioning, and identity semantics.

Quick Start

1. Add the component to your ESP-IDF project (e.g., via EXTRA_COMPONENT_DIRS).
2. Provide UART callbacks when constructing DaliComm:

DaliComm comm(
    /* send */ [](const uint8_t* data, size_t len) {
      // write bytes to the gateway UART
      return my_uart_write(data, len) == ESP_OK;
    },
    /* read (optional) */ [](size_t len, uint32_t timeoutMs) -> std::vector<uint8_t> {
      return my_uart_read(len, timeoutMs);
    },
    /* transact */ [](const uint8_t* data, size_t len) -> std::vector<uint8_t> {
      my_uart_write(data, len);
      return my_uart_read_response(); // should return the raw gateway reply
    });
Dali dali(comm);

3. Use the API just like the Dart version:

dali.base.setBright(5, 200);         // direct arc power control
dali.base.setBright(5, 128, true);   // direct arc power with logarithmic curve
dali.base.off(5);
dali.base.dtSelect(8);
dali.dt8.setColorTemperature(5, 4000); // Kelvin
std::vector<int> rgb = dali.dt8.getColourRGB(5);

Behaviour Parity

• Frame formats match the Dart implementation: [0x10, addr, cmd] (send), [0x11, addr, cmd] (extended), [0x12, addr, cmd] (query with [0xFF, data] response).
• Address encoding matches Dart helpers: dec*2 for direct arc, dec*2+1 for command/query addresses.
• Colour conversion utilities (rgb2xy, xy2rgb, XYZ/LAB helpers) are ported from lib/dali/color.dart.
• Public APIs from base.dart, dt8.dart, dt1.dart, addr.dart, and decode.dart are exposed with matching method names.
• App-side model parity modules are included for device.dart, sequence.dart, and sequence_store.dart via device.hpp, sequence.hpp, and sequence_store.hpp.
• Utility APIs from errors.dart, log.dart, query_scheduler.dart, and bus_monitor.dart are available as embedded-friendly C++ headers.

Generic Bridge Layer

The component now includes a protocol-agnostic bridge layer for mapping external fieldbus models into DALI operations.

Bridge Building Blocks

• bridge_model.hpp defines the strongly typed mapping model: protocol kind, external point, DALI target, default operation, and value transform.
• bridge.hpp provides DaliBridgeEngine, which resolves models and dispatches requests into DaliComm, DaliBase, and DaliDT8.
• bridge_provisioning.hpp provides BridgeProvisioningStore for persisting bridge models in ESP-IDF NVS.
• Modbus and BACnet runtime support are owned by the native gateway project in gateway/components/gateway_modbus and gateway/components/gateway_bacnet.

Example Model Mapping

BridgeModel brightness;
brightness.id = "line-1-brightness";
brightness.name = "Line 1 brightness";
brightness.dali.shortAddress = 1;
brightness.operation = BridgeOperation::setBrightness;
brightness.valueTransform.clampMin = 0;
brightness.valueTransform.clampMax = 254;

DaliBridgeEngine engine(comm);
engine.upsertModel(brightness);

DaliBridgeRequest request;
request.modelID = "line-1-brightness";
request.value = 180;
engine.execute(request);

request.value = DaliValue::Object{{"value", 128}, {"logarithmicCurve", true}};
engine.execute(request); // set_brightness with app-side logarithmic curve

Supported Bridge Operations

• send
• send_ext
• query
• set_brightness
• set_brightness_percent
• on
• off
• recall_max_level
• recall_min_level
• set_color_temperature
• get_brightness
• get_status
• get_color_temperature
• get_color_status
• get_emergency_level
• get_emergency_status
• get_emergency_failure_status
• start_emergency_function_test
• stop_emergency_test

set_brightness and set_brightness_percent accept optional logarithmicCurve / logarithmic_curve boolean request fields.

Query-style operations return data when available and may include decoded flags in meta.

Notes

• Query support works with either a read callback or a transact callback. When read is available, queries return as soon as the reply bytes arrive instead of waiting behind a fixed pre-read delay.
• Dali facade in include/dali.hpp mirrors lib/dali/dali.dart and wires base, decode, dt1, dt8, and addr together.
• The t, d, and g parameters in Dart are not required here; timing/gateway selection is driven by your callbacks.
• DaliCloudBridge now uses the shared bridge engine internally, so MQTT downlinks can target either raw DALI frames or registered bridge models.

Bridge Provisioning via NVS

Use BridgeProvisioningStore to persist bridge models:

BridgeRuntimeConfig runtime;
runtime.models.push_back(brightness);

BridgeProvisioningStore store;
store.save(runtime);

BridgeRuntimeConfig loaded;
if (store.load(&loaded) == ESP_OK) {
  // register loaded.models with DaliBridgeEngine
}

The gateway project stores Modbus TCP settings in the same persisted JSON shape, but parses and applies that section in gateway/components/gateway_modbus rather than in this standalone DALI component.

Cloud Bridge (ESP32 Gateway)

The component now includes DaliCloudBridge in include/gateway_cloud.hpp to connect ESP32 gateways to the backend MQTT broker.

Topics

• Downlink: devices/<deviceID>/down
• Uplink: devices/<deviceID>/up
• Status: devices/<deviceID>/status
• Register: devices/<deviceID>/register

Downlink JSON Envelope

{
  "type": "dali_cmd",
  "seq": "123",
  "model": "modbus-light-1",
  "op": "send|send_ext|query",
  "addr": 5,
  "cmd": 160,
  "shortAddress": 1,
  "value": 180
}

model, shortAddress, and value are optional. If model is provided, the bridge resolves its mapped DALI target and default operation.

Successful query responses may also include a meta object with decoded status flags.

Uplink JSON Envelope

{
  "type": "dali_resp",
  "seq": "123",
  "op": "query",
  "ok": true,
  "data": 255
}

Usage

GatewayCloudConfig cfg;
cfg.brokerURI = "mqtt://192.168.1.100:1883";
cfg.deviceID = "A1B2C3D4E5F6";
cfg.username = "device";
cfg.password = "A1B2C3D4E5F6";

DaliCloudBridge bridge(comm);
if (bridge.start(cfg)) {
  bridge.publishStatus("online");
}

Provisioning via NVS

Use GatewayProvisioningStore to persist cloud connection settings:

GatewayProvisioningStore store;
GatewayCloudConfig cfg;
cfg.brokerURI = "mqtt://192.168.1.100:1883";
cfg.deviceID = "A1B2C3D4E5F6";
cfg.username = "device";
cfg.password = "A1B2C3D4E5F6";

store.save(cfg);

GatewayCloudConfig loaded;
if (store.load(&loaded) == ESP_OK) {
  DaliCloudBridge bridge(comm);
  bridge.start(loaded);
}

ESP32-S3 Example Project

A standalone ESP-IDF example app is available at examples/esp32s3_bridge/.

Environment Setup

Source the helper script from your shell so the exported ESP-IDF variables stay in your session:

. ./scripts/export_esp_idf.sh

The helper script sources the installed ESP-IDF v5.5.4 export.sh.

Build the Example

cd examples/esp32s3_bridge
idf.py set-target esp32s3
idf.py build

The example persists its bridge config in NVS, registers generic bridge models, and routes requests through the shared bridge engine. The DALI gateway callbacks are still placeholders where you should connect your UART or transport driver. Use gateway/apps/gateway to exercise the gateway-owned Modbus and BACnet runtimes.