Tony
a8a82f9627
- Introduced DaliCloudBridge for MQTT communication with backend. - Added GatewayProvisioningStore for persisting cloud connection settings using NVS. - Updated CMakeLists.txt to include new source files. - Enhanced README.md with usage examples and configuration details.
121 lines
3.6 KiB
Markdown
121 lines
3.6 KiB
Markdown
# DALI ESP-IDF Component
|
|
|
|
A lightweight C++ implementation of the DALI stack used in `lib/dali/*.dart` for gateway type 1 (USB UART) traffic. The component mirrors Dart method names so it can be used as an embedded replacement target.
|
|
|
|
## Quick Start
|
|
|
|
1. Add the component to your ESP-IDF project (e.g., via `EXTRA_COMPONENT_DIRS`).
|
|
2. Provide UART callbacks when constructing `DaliComm`:
|
|
|
|
```cpp
|
|
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:
|
|
|
|
```cpp
|
|
dali.base.setBright(5, 200); // direct arc power control
|
|
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.
|
|
|
|
## Notes
|
|
|
|
- Optional query support: provide a `transact` callback that returns the gateway reply; otherwise, query methods return `std::nullopt`.
|
|
- `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.
|
|
|
|
## 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
|
|
|
|
```json
|
|
{
|
|
"type": "dali_cmd",
|
|
"seq": "123",
|
|
"op": "send|send_ext|query",
|
|
"addr": 5,
|
|
"cmd": 160
|
|
}
|
|
```
|
|
|
|
### Uplink JSON Envelope
|
|
|
|
```json
|
|
{
|
|
"type": "dali_resp",
|
|
"seq": "123",
|
|
"op": "query",
|
|
"ok": true,
|
|
"data": 255
|
|
}
|
|
```
|
|
|
|
### Usage
|
|
|
|
```cpp
|
|
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:
|
|
|
|
```cpp
|
|
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);
|
|
}
|
|
```
|