6. Firmware INTERNAL

Introduction

Firmware labeled as INTERNAL enables the device to operate independently as an eBUS device, eliminating the need for external control software like ebusd. To assess both passively received and actively sent commands, these must be installed in the internal command store. The outcomes of evaluated messages can be saved in this store, actively sent via MQTT, or accessed through HTTP.

Key Features:

• Port Access: Read and write operations are facilitated through ports 3333, 3334, and 3335 (supporting the ebusd enhanced protocol).
• Status Queries: Status checks can be conducted through port 5555.
• Internal Command Store: Supports both active and passive commands.
• Command Installation: Commands can be installed via MQTT or HTTP uploads.
• Persistent Storage: Installed commands are saved in NVS memory and automatically loaded upon device restart.
• Message Evaluation: Received or sent messages are processed, with results published to MQTT.
• Non-Installed Command Support: Non-installed commands can be sent via MQTT.
• eBUS Device Scanning: The system supports scanning for eBUS devices.
• Startup Scanning: Automatic detection of eBUS devices occurs during startup.
• Message Forwarding: Messages recognized through patterns can be forwarded via MQTT.
• Value Reading/Writing: The system allows reading values from stored commands via MQTT and writing values using these commands.
• Home Assistant Auto Discovery: Available for certain types of devices.

This firmware is powered by the ebus library, which can be found at C++ library for eBUS communication.

Structure of the internal command store

For an example of how to install a command via MQTT, see Inserting (Installing) of new commands.

struct Command {
  // Command Fields
  std::string key = "";                             // unique key of command
  std::string name = "";                            // name of the command used as mqtt topic below "values/"
  std::vector<uint8_t> read_cmd = {};               // read command as vector of "ZZPBSBNNDBx"
  std::vector<uint8_t> write_cmd = {};              // write command as vector of "ZZPBSBNNDBx" (OPTIONAL)
  bool active = false;                              // active sending of command
  uint32_t interval = 60;                           // minimum interval between two commands in seconds (OPTIONAL)
  uint32_t last = 0;                                // last time of the successful command (INTERNAL)
  std::vector<uint8_t> data = {};                   // received raw data (INTERNAL)
  
  // Data Fields
  bool master = false;                              // value of interest is in master or slave part
  size_t position = 1;                              // starting position
  ebus::DataType datatype = ebus::DataType::HEX1;   // ebus data type
  size_t length = 1;                                // length (INTERNAL)
  bool numeric = false;                             // indicate numeric types (INTERNAL)
  float divider = 1;                                // divider for value conversion (OPTIONAL)
  float min = 1;                                    // minimum value (OPTIONAL)
  float max = 100;                                  // maximum value (OPTIONAL)
  uint8_t digits = 2;                               // decimal digits of value (OPTIONAL)
  std::string unit = "";                            // unit (OPTIONAL)
          
  // Home Assistant (OPTIONAL)          
  bool ha = false;                                  // home assistant support for auto discovery
  std::string ha_component = "";                    // home assistant component type
  std::string ha_device_class = "";                 // home assistant device class
  std::string ha_entity_category = "";              // home assistant entity category
  std::string ha_mode = "auto";                     // home assistant mode
  std::map<int, std::string> ha_key_value_map = {}; // home assistant options as pairs of "key":"value"
  int ha_default_key = 0;                           // home assistant options default key
  uint8_t ha_payload_on = 1;                        // home assistant payload for ON state
  uint8_t ha_payload_off = 0;                       // home assistant payload for OFF state
  std::string ha_state_class = "";                  // home assistant state class
  float ha_step = 1;                                // home assistant step value
};

Available ebus data types:

• numeric: BCD, UINT8, INT8, DATA1B, DATA1C, UINT16, INT16, DATA2B, DATA2C, UINT32, INT32, FLOAT (IEEE 754)
• character: CHAR1 - CHAR8, HEX1 - HEX8