Open FirenetAPI reference
Every endpoint of the bridge, with its fields, types, units and ranges. Generated from the OpenAPI description of firmware 3.6.0.
Local REST API of the Open Firenet bridge, the ESP32-S3 that replaces the RIKA Firenet stick. It is served on your network at http://open-firenet.local (or the bridge's IP address), without key or account.
Units are natural ones: temperatures in °C, power in percent, readable mode names.
Field names. Only the recommended names are described here, the ones used by the Home Assistant integration and by MQTT. For historical reasons the bridge also accepts older aliases in commands (for example tempRoomTarget for target_temperature, or the plain-text form onOff=1; heatingPower=70;), and GET /api/controls also returns the settings under the stove's own names and units (onOff, tempRoomTarget in tenths of a degree...). New code should not rely on them.
Before the stove is linked. Until the stove has answered, version_ack is false, the stove model and firmware version are null, and the other values are defaults, not measurements.
Endpoints
| Endpoint | Purpose |
|---|---|
GET /api/state | Everything at once |
GET /api/controls | Current settings |
POST /api/controls | Change settings |
GET /api/schedule | Weekly heating schedule |
POST /api/schedule | Change the weekly heating schedule |
GET /api/mqtt | MQTT settings and connection status |
POST /api/mqtt | Change the MQTT settings |
GET /api/version | Firmware version of the bridge |
GET /api/scan | Wi-Fi networks seen by the bridge |
POST /api/wifi | Set the Wi-Fi network, then restart |
POST /api/forget | Erase the saved settings, then restart in setup mode |
GET /api/restart | Restart the bridge |
POST /api/restart | Restart the bridge |
GET /api/txgap | Delay between frames sent to the stove |
POST /api/txgap | Change the delay between frames sent to the stove |
GET /log | Log of the exchanges with the stove |
Stove
Read the stove and change its settings
GET /api/state
Everything at once
Bridge, stove, sensors, settings and link diagnostics. This is what the web page and the Home Assistant integration poll.
Answer 200 Current state
Fields: see State.
GET /api/controls
Current settings
Answer 200 The settings, under the recommended names (the stove's own names and units are returned too)
Fields: see Controls.
POST /api/controls
Change settings
Send only the fields to change; the others keep their value. Ignored while the stove is not linked. On stove firmware 2.28 only on, mode, power_percent and target_temperature are applied.
Request body application/json
Fields: see ControlsCommand.
21 °C in comfort mode:
{"target_temperature": 21, "mode": "comfort"}Switch on at 80 % power:
{"on": true, "power_percent": 80}Answer 200 The base settings sent to the stove
Fields: see ControlsResult.
GET /api/schedule
Weekly heating schedule
Answer 200 The 14 time slots and the setback temperature
Fields: see Schedule.
POST /api/schedule
Change the weekly heating schedule
Same handling as POST /api/controls; send the slots to change under their names.
Request body application/json
Fields: see ScheduleCommand.
Example:
{"heating_times_active": true, "setback_temperature": 16, "heatTimeMon1": 6000800, "heatTimeMon2": 17002200}Answer 200 The base settings sent to the stove
Fields: see ControlsResult.
Bridge
Settings and maintenance of the bridge itself
GET /api/mqtt
MQTT settings and connection status
Answer 200 The settings (the password is never returned) and the status
Fields: see Mqtt.
POST /api/mqtt
Change the MQTT settings
A field left out keeps its value. The client restarts with the new settings; the status follows at the next GET.
Request body application/json
Fields: see MqttCommand.
Answer 200 The saved settings
Fields: see Mqtt.
GET /api/version
Firmware version of the bridge
Answer 200 Version and build date
Fields: see Version.
GET /api/scan
Wi-Fi networks seen by the bridge
The first call starts a scan and answers 202; call again a few seconds later for the list.
Answer 200 Networks found (2.4 GHz), each name once
A list of:
| Field | Type | Description |
|---|---|---|
ssid required | string | |
rssi required | integer | Signal strength in dBm |
Answer 202 Scan in progress
| Field | Type | Description |
|---|---|---|
status | scanning |
POST /api/wifi
Set the Wi-Fi network, then restart
Sent by the setup form. Answers an HTML confirmation page (it has to work in captive portal browsers), then the bridge restarts on that network.
Request body application/x-www-form-urlencoded
| Field | Type | Description |
|---|---|---|
ssid required | string | |
pass | string | Empty for an open network |
Answer 200 Saved; the bridge restarts
text/html
Answer 400 Missing network name
text/html
POST /api/forget
Erase the saved settings, then restart in setup mode
Erases the Wi-Fi network, the MQTT settings and the frame delay. The bridge then creates the Open-Firenet-Setup network.
Answer 200 Erased; the bridge restarts
| Field | Type | Description |
|---|---|---|
ok | boolean |
GET /api/restart
Restart the bridge
Any method is accepted; the web page uses POST. The stove keeps running; the link comes back in about a minute.
Answer 200 The bridge restarts
| Field | Type | Description |
|---|---|---|
ok | boolean | |
reboot | boolean |
POST /api/restart
Restart the bridge
Answer 200 The bridge restarts
| Field | Type | Description |
|---|---|---|
ok | boolean | |
reboot | boolean |
Diagnostics
GET /api/txgap
Delay between frames sent to the stove
Answer 200 Current delay and its bounds
Fields: see TxGap.
POST /api/txgap
Change the delay between frames sent to the stove
Diagnostic setting, kept after a restart. Too low, the stove may only process one frame out of two.
Request body application/json
| Field | Type | Description |
|---|---|---|
ms required | integer, 50 to 600 | Delay in milliseconds |
Answer 200 The delay now in use
Fields: see TxGap.
GET /log
Log of the exchanges with the stove
Plain text, one line per frame: [uptime in ms][rx|tx] content. Identical consecutive lines are merged (xN). The Wi-Fi password is masked. Kept in memory only (about the last 32 kB).
Answer 200 The log
text/plain
Objects
The objects exchanged with the bridge, referred to above.
State
| Field | Type | Description |
|---|---|---|
device required | Device | |
stove required | Stove | |
sensors required | Sensors | |
controls required | ControlsState | |
wifi_mode | STA | AP | AP while the bridge is in setup mode |
ip | string | |
wifi_connected | boolean | |
uptime_seconds | integer | |
write_enabled | boolean | Always true |
version_ack required | boolean | Whether the stove accepted the bridge (the link is up) |
version_frame | V3 | V28 | V1 | ? | Protocol variant the stove answered: V3 (firmware 2.29), V28 (2.28), V1 (2.26 / 2.27) |
generation | integer | |
usb required | object | USB link diagnostics |
mqtt | object | |
frames_in | integer | Frames received from the stove since boot |
frames_out | integer | Frames sent to the stove since boot |
revision | integer | |
state_label | string | |
raw_sensors required | object, any name → integer | Every value the stove reports, under its RIKA name, in the stove's units (temperatures often in tenths of a degree). Empty until the stove is linked. |
status | object, any name → string | Status record exchanged with the stove (the Wi-Fi password is masked) |
sensors_pos | list of integer | The sensor records by position (diagnostics) |
controls_pos | list of integer | The control records by position (diagnostics) |
Device
The bridge
| Field | Type | Description |
|---|---|---|
name | string | |
version | string | Firmware version of the bridge |
app_version | string | Same as version |
firmware_version | string | Same as version |
ip | string | |
mac | string | |
wifi_ssid | string | |
wifi_rssi | integer | Wi-Fi signal in dBm |
uptime_seconds | integer | |
free_heap | integer | Free memory in bytes |
ota_slot_bytes | integer | Size in bytes of the slot a wireless update is written to. A firmware larger than this must be installed over USB |
connected | boolean | Same as version_ack |
Stove
| Field | Type | Description |
|---|---|---|
state | off | standby | ignition | flame_start | heating | cleaning | burn_off | splitlog | unknown | |
state_code | integer | |
state_label | string | |
sub_state | integer | |
is_burning | boolean | |
has_error | boolean | |
error_code | integer | 0 when there is no error |
error_sub | integer | |
warning_code | integer | 0 when there is no warning |
model | integer or null | RIKA model number, null until the stove has sent it |
model_name | string or null | For example DOMO; null until the stove has sent it |
mainboard_version | string or null | Stove firmware, for example 2.29; null until the stove has sent it |
firmware_build | string or null |
Sensors
| Field | Type | Description |
|---|---|---|
room_temperature | number or null | °C; null when no RIKA room sensor is connected |
room_sensor_connected | boolean | |
combustion_temperature | number | °C |
board_temperature | number | °C |
pellets_total_kg | integer | |
pellet_hours | integer | Running hours |
service_countdown_kg | integer | Pellets left before the next service |
fan_speed_rpm | integer | |
auger_speed_rpm | integer | |
air_flaps_percent | number or null | |
air_flaps_target_percent | number or null |
ControlsState
The current settings
| Field | Type | Description |
|---|---|---|
on | boolean | |
mode | manual | auto | comfort | manual: fixed power. auto: follows the weekly schedule. comfort: follows the room temperature. |
mode_code | integer | 0 = manual, 1 = auto, 2 = comfort |
target_temperature | number | °C |
power_percent | integer | |
heating_times_active | boolean | Weekly schedule on / off |
setback_temperature | number | °C outside the scheduled slots |
convection_fan1_active | boolean | |
convection_fan1_level | integer | 0 = automatic, 1 to 5 |
convection_fan1_area | integer | Trim in percent, -30 to +30 |
convection_fan2_active | boolean | |
convection_fan2_level | integer | |
convection_fan2_area | integer | |
frost_protection_active | boolean | |
frost_protection_temperature | number | °C |
bake_target_temperature | integer | °C (DOMO BACK only) |
room_temperature_offset | number | Room sensor calibration in °C |
eco_mode | boolean | |
eco_mode_possible | boolean | Whether the stove allows eco mode right now |
Controls
The current settings. The stove's own names (onOff, tempRoomTarget...) are returned as well and are not described here.
| Field | Type | Description |
|---|---|---|
on | boolean | |
mode | manual | auto | comfort | manual: fixed power. auto: follows the weekly schedule. comfort: follows the room temperature. |
mode_code | integer | |
target_temperature | number | |
power_percent | integer | |
heating_times_active | boolean | |
setback_temperature | number | |
frost_protection_active | boolean | |
frost_protection_temperature | number | |
bake_target_temperature | integer | |
room_temperature_offset | number | |
eco_mode | boolean | |
| other fields | Not described here. |
ControlsCommand
Any subset of these fields
| Field | Type | Description |
|---|---|---|
on | boolean | |
mode | manual | auto | comfort | manual: fixed power. auto: follows the weekly schedule. comfort: follows the room temperature. |
power_percent | integer, 30 to 100 | |
target_temperature | number, 14 to 28 | °C, in whole degrees: a half degree is rounded |
heating_times_active | boolean | |
setback_temperature | number | °C |
frost_protection_active | boolean | |
frost_protection_temperature | number, 4 to 10 | °C |
room_temperature_offset | number, -4 to 4 | °C |
bake_target_temperature | integer, 130 to 340 | °C (DOMO BACK only) |
eco_mode | boolean | |
convection_fan1_active | boolean | |
convection_fan1_level | integer, 0 to 5 | 0 = automatic |
convection_fan1_area | integer, -30 to 30 | |
convection_fan2_active | boolean | |
convection_fan2_level | integer, 0 to 5 | |
convection_fan2_area | integer, -30 to 30 |
ControlsResult
| Field | Type | Description |
|---|---|---|
ok | boolean | |
on | boolean | |
mode | manual | auto | comfort | manual: fixed power. auto: follows the weekly schedule. comfort: follows the room temperature. |
mode_code | integer | |
target_temperature | number | |
power_percent | integer |
Schedule
| Field | Type | Description |
|---|---|---|
ok | boolean | |
active | boolean | Weekly schedule on / off |
heatingTimesActive | integer | Same as active, as 0 / 1 |
setback_temperature | number | °C outside the scheduled slots |
setBackTemp | integer | Same, in tenths of a degree |
slots | object, any name → integer | Two slots per day, heatTime<Day><1|2> with Day in Mon, Tue, Wed, Thu, Fri, Sat, Sun |
ScheduleCommand
heating_times_active, setback_temperature, and any of the 14 slots heatTime<Day><1|2>
| Field | Type | Description |
|---|---|---|
heating_times_active | boolean | |
setback_temperature | number | |
| any other name | integer | A heating slot as one number: start HHMM times 10000, plus end HHMM. 6000800 is 06:00 to 08:00, 17002200 is 17:00 to 22:00, 0 is an unused slot. |
Mqtt
| Field | Type | Description |
|---|---|---|
enabled | boolean | |
host | string | |
port | integer | |
user | string | |
password_set | boolean | Whether a password is stored (it is never returned) |
base_topic | string | |
discovery | boolean | Whether the Home Assistant discovery messages are published |
tls | boolean | Whether the connection to the broker is encrypted (MQTT over TLS) |
ca_set | boolean | Whether an authority certificate is stored (it is not returned) |
tls_error | integer | Last error code of the TLS layer, 0 when none (diagnostics) |
connected | boolean | |
status | disabled | connected | connecting | waiting for Wi-Fi | broker unreachable | connection lost | certificate not trusted | secure connection failed | refused: wrong user or password | refused by the broker |
MqttCommand
| Field | Type | Description |
|---|---|---|
enabled | boolean | |
host | string | Broker address |
port | integer | Default: 1883. |
user | string | |
password | string | Empty to erase the stored one |
base_topic | string | Default: openfirenet. |
discovery | boolean | Home Assistant MQTT discovery: the stove appears by itself in Home Assistant. Leave it off when the Open Firenet integration is used Default: False. |
tls | boolean | Encrypted connection (MQTT over TLS, usually port 8883). The broker's certificate must be signed by a public authority, or by the one given in ca_certificate Default: False. |
ca_certificate | string | Certificate (PEM) of your own authority, for a broker whose certificate is not signed by a public one; the name in the broker's certificate is then not checked. Empty to erase the stored one. Refused with a 400 answer when it is not a PEM certificate |
TxGap
| Field | Type | Description |
|---|---|---|
ms | integer | |
default | integer | |
min | integer | |
max | integer |
Version
| Field | Type | Description |
|---|---|---|
app | string | |
version | string | |
build_date | string | |
build_time | string | |
target | string |