eFIRE Bluetooth Protocol

Basic Communication

Communication with the eFIRE controller is facilitated the through Generic Attribute Profile (GATT) via a Bluetooth LE connection.

Commands can be sent to the controller through the write characteristic at UUID 0000ff01-0000-1000-8000-00805f9b34fb. Responses to these commands can be read by subscribing to notifications on the read characteristic at UUID 0000ff02-0000-1000-8000-00805f9b34fb.

General packet format

The eFIRE Controller uses a binary protocol that follows a TLV schema.

        ---
config:
  packet:
    bitsPerRow: 16

---
packet
    0-7: "Header (0xAB)"
    8-15: "Message Type (0xAA or 0xBB)"
    16-23: "Length"
    24-31: "Command"
    32-47: "Data (variable length)"
    48-55: "Checksum (XOR)"
    56-63: "Footer (0x55)"

Message Type specifies whether the packet is a request (0xAA) or a response (0xBB).

The length is given as an unsigned 8-bit integer and denotes the length of the remaining packet including the footer. Specifically, the length includes the following fields: Command, Data, Checksum and Footer.

The commands are detailed in their own section below.

The checksum is an XOR over the following fields: Length, Command and Data.

A complete message in this format with a valid checksum could look like this:

0xAB 0xBB 0x06 0xF2 0x00 0x08 0x00 0xFF 0x55

This is a response from the 0xF2: Get BLE Version command.

Commands

This section describes all commands that can be sent to the controller and their respective parameters.

0x27: IFC CMD1

This command interacts with the first set of settings of the IFC. This first set of settings comprises:

  1. Power (0 (off) or 1 (on))

  2. Thermostat (0 (off) or 1 (on))

  3. Night Light Level (0-6)

  4. Continuous Pilot (0 (Intermittent Pilot) or 1 (Continuous Pilot))

Payload format:

        ---
config:
  packet:
    bitWidth: 72
    bitsPerRow: 8

---
packet
    0: "Power"
    1: "Thermostat"
    2-3: "Reserved"
    4-6: "Night Light"
    7: "Pilot"
    8-15: "Reserved (always 0x00)"
parameters:
CMD1 Payload (2 bytes)

The first byte is always 0x00.

Example: 0x00E3 for Power On, Thermostate enabled, Night Light Level 6, Continuous Pilot enabled.

return:

  • 0x00: Success

  • 0x01: Failure

0x28: IFC CMD2

This command interacts with the second set of settings of the IFC. This second set of settings comprises:

  1. Flame Height (0-6)

  2. Blower Speed (0-6)

  3. Aux Relay (0 (off) or 1 (on))

  4. Split Flow (0 (off) or 1 (on))

Payload format:

        ---
config:
  packet:
    bitWidth: 72
    bitsPerRow: 8

---
packet
    0-2: "Flame Height"
    3: "AUX Relay"
    4-6: "Blower Speed"
    7: "Split Flow"
    8-15: "Reserved (always 0x00)"
parameters:
CMD2 Payload (2 bytes)

The first byte is always 0x00.

Example: 0x00EE for Flame Height 6, AUX Relay on, Blower Speed 6, Split Flow Valve enabled

return:

  • 0x00: Success

  • 0x01: Failure

0xB1: Set LED Power

Turns the LED Controller on or off.

parameters:
Desired LED state (3 bytes)

  • 0xFFFFFF: On

  • 0x000000: Off

return:

  • 0x00: Success

  • 0x01: Failure

0xC1: Set LED Color

Set the LED color on the LED controller.

parameters:
Desired LED color in hex RGB format (3 bytes)

Example: 0xFFFFFF for white

return:

  • 0x00: Success

  • 0x01: Failure

0xC3: Set Timer

Set the sleep timer on the controller.

parameters:
Hours (1 byte)

Example: 0x03 for 3 hours

Minutes (1 byte)

Example: 0x0f for 15 minutes

Timer state (1 byte)

  • 0x01: Enable Timer

  • 0x00: Disable Timer

return:

  • 0x00: Success

  • 0x01: Failure

0xC4: Set Power

Turns the burner on or off.

parameters:
Desired burner state (1 byte)

  • 0xFF: On

  • 0x00: Off

return:

  • 0x00: Success

  • 0x01: Failure

0xC5: Send Password

Sends a password to the controller.

Used without any preceding password management commands this will authenticate the connection using the supplied password. When used in conjunction with the 0xC6 command while supplying the 0xF5 parameter it is used to set a new password.

parameters:
Password as ASCII encoded bytes (variable length)

Example: 0x30303030 for a password of “0000”

Warning

Maximum length and non-numeric passwords have not been tested!

return:

  • 0x00: Password successfully set

  • 0x01: Set password failed

  • 0x19: Invalid password

  • 0x35: Password accepted

0xC6: Password Management

Initiate a password management action. Used in conjunction with 0xC5 to set a new password.

parameters:
Password action to initiate (1 byte)

  • 0x3F: Reset Password

  • 0xF5: Set Password

return:

  • 0x00: Success

  • 0x01: Failure

0xC7: Sync Timer

Sync local and controller timer values. The eFIRE app presumably uses this to remove time drift between the app timer display and the remaining time on the controller.

parameters:
Hours (1 byte)

Example: 0x03 for 3 hours

Minutes (1 byte)

Example: 0x0f for 15 minutes

Seconds (1 byte)

Example: 0x30 for 48 seconds

return:

  • 0x00: Success

  • 0x01: Failure

0xE0: Get LED Controller Power State

Get the power state of the optional LED controller.

return:

  • 0x000000: LEDs are off

  • 0xFFFFFF: LEDs are on

0xE1: Get LED Color

Get the current color setting from the LED controller.

return:

  • RGB Hex value of the color

    Example: 0xFF0000 for red

0xE2: Get LED Mode

Get the current mode setting from the LED controller.

return:

  • 0x010101: Cycle (i.e. rainbow cycle)

  • 0x020202: Hold (i.e. single color)

  • 0xFFFFFF: Ember Bed (i.e. fire effect)

0xE3: Get IFC CMD1 State

Get the current IFC CMD1 state.

return:

Returns 2 bytes corresponding to the format described in the 0x27: IFC CMD1 section.

Example: 0x00E3

0xE4: Get IFC CMD2 State

Get the current IFC CMD2 state.

return:

Returns 2 bytes corresponding to the format described in the 0x28: IFC CMD2 section.

Example: 0x00EE

0xE6: Get Timer

Get the timer settings.

return:
Hours (1 byte)

Example: 0x03 for 3 hours

Minutes (1 byte)

Example: 0x0f for 15 minutes

Timer state (1 byte)

  • 0x01: Timer enabled

  • 0x00: Timer enabled

Seconds (1 byte)

Example: 0x30 for 48 seconds

0xE7: Get Power State

Get the power state of the fireplace.

return:
Current fireplace power state (1 byte)

  • 0x00: Off

  • 0xFF: On

0xE8: Get Password

Get the password currently set on the controller.

return:
Password as ASCII encoded bytes (variable length)

Example: 0x30303030 for a password of “0000”

0xE9: Query Set Password Result

Returns the result from the last password set command.

return:
Current fireplace power state (1 byte)

  • 0x25: Password set failed

  • 0x53: Password set successful

0xEA: Time Sync

read time sync from ctrl

0xEB: Get LED Controller State

Return the current overall state of the LED controller.

return:
Current LED controller power state (1 byte)

  • 0x00: Off

  • 0xFF: On

Current LED controller RGB Hex color setting (3 bytes)

Example 0xFF0000 for red

Current LED controller mode (1 byte)

  • 0x01: Cycle (i.e. rainbow cycle)

  • 0x02: Hold (i.e. single color)

  • 0xFF: Ember Bed (i.e. fire effect)

0xF1: Set LED Controller Mode

Set the LED Controller mode.

parameters:
Desired LED controller mode (1 byte)

  • 0x10: Ember Bed (i.e. fire effect)

  • 0x20: Cycle (i.e. rainbow cycle)

  • 0x30: Hold (i.e. single color)

return:

  • 0x00: Success

  • 0x01: Failure

0xF2: Get BLE Version

Get the firmware version of the BLE module.

return:
BLE Firmware version (3 bytes)

Example: 0x000800 is parsed by the app as version string “8”

0xF3: Get MCU Version

Get the firmware version of the MCU.

return:
MCU Firmware version (3 bytes)

Example: 0x010104 is parsed by the app as version string “1.14”

0xF4: Get Auxiliary Control

Note

Untested. Does not return anything on my device

Return whether the fireplace is currently controlled by the RF remote.

If the fireplace is controlled by the RF remote Bluetooth commands have no effect and state reported by the controller is invalid.