Table of Contents
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
JSON Commands
Information is exchanged between the ESP32 and remote clients using JSON string formatting.
i.e. {"name1":value1,"name2":value2}
Only actual value changes are transmitted to minimise traffic.
However, whenever a new client attaches to the ESP32, every client will receive the full set of information.
i.e. every time a client connects, they will always get the complete status of the heater, then only changes to the values, unless another user connects.
Some parameters are only sent upon being requested via a "Query" command, eg "MQuery" delivers MQTT setup parameters, "SQuery" delivers system parameters, etc.
The table below documents the JSON names sent between the ESP32 and Bluetooth or WiFi clients.
Some commands are bi-directional, others are simply command directives (to ESP32), or status reporting (from ESP32).
Certain commands are used to alter the non volatile settings stored by the controller. eg Fuel mixture, timers.
These must be followed up with a NVSave command.
| Name | Value Type | Typical Values | Direction | Require NVsave | Note |
|---|---|---|---|---|---|
| BluewireStat | string | "OEM" or "BTC" + ",Htr" (if present) | From ESP | n/a | |
| CyclicTemp | integer | 8-35 | To/From ESP | no | set point temperature always |
| CyclicOff | integer | 0,2..10 | To/From ESP | YES | cyclic off threshold (1 is invalid) 0=disabled |
| CyclicOn | integer | -20..0 | To/From ESP | YES | cyclic restart threshold |
| ErrorState | integer | 0..11 | From ESP | n/a | |
| ErrorString | string | "verbose description" | From ESP | n/a | |
| FanMax | float | RPM | To/From ESP | YES | |
| FanMin | float | RPM | To/From ESP | YES | |
| FanSensor | integer | 1,2 | To/From ESP | YES | |
| FanRPM | integer | RPM | From ESP | n/a | |
| FanVoltage | float | 0.1V resolution | From ESP | n/a | |
| GlowCurrent | float | 10mA resolution | From ESP | n/a | |
| GlowVoltage | float | 0.1V resolution | From ESP | n/a | |
| GPanlg | int | 0-100 | From ESP | n/a | GPIO analogue input % |
| GPin1 / GPin2 | int | 0,1 | From ESP | n/a | GPIO input state |
| GPout1 / GPout2 | int | 0,1 | To/From ESP | no | GPIO output state |
| GPmodeAnlg | string | description | From ESP | no | GPIO analogue mode: Disabled General HeatDemand |
| GPmodeIn1 | string | description | From ESP | no | GPIO input # 1 mode: Disabled Mom On HoldOn Mom On/Off Mom Off |
| GPmodeIn2 | string | description | From ESP | no | GPIO input # 2 mode: Disabled Mom Off Ext Thermo |
| GPmodeOut1 | string | description | From ESP | no | GPIO output # 1 mode: Disabled Status User |
| GPmodeOut2 | string | description | From ESP | no | GPIO output # 2 mode: Disabled User |
| InputVoltage | float | 0.1V resolution | From ESP | n/a | |
| LowVoltCutout | float | 12V 10.0 .. 12.5 24V 20.0 .. 25.0 |
To/From ESP | YES | Low voltage protection 0 disables |
| NVsave | int | 8861 | To ESP | n/a | must be 8861 |
| PumpActual | float | 0.1Hz resolution | From ESP | n/a | |
| PumpCal | float | description | To/From ESP | YES | mL / stroke of pump |
| PumpCount | float | description | To/From ESP | n/a | Integrated pump strokes (fuel gauge) Send 0 to reset |
| PumpFixed | float | 0.1Hz resolution | From ESP | n/a | |
| PumpPrime | int | 0,1 | To ESP | no | |
| PumpMax | float | 0.1Hz resolution | To/From ESP | YES | |
| PumpMin | float | 0.1Hz resolution | To/From ESP | YES | |
| Refresh | int | 1 | To ESP | no | Request full update |
| RunState | integer | 0..8 | To/From ESP | no | |
| RunString | string | "verbose description" | From ESP | n/a | |
| SystemVoltage | float | 12.0 or 24.0 | To/From ESP | YES | must be 12.0 or 24.0 |
| TempBody | integer | 1degC resolution | From ESP | n/a | |
| TempCurrent | float | typ 0.1degC temperature | From ESP | n/a | |
| TempDesired | integer | 8 - 35, 1degC resolution | To/From ESP | YES | |
| TempMax | integer | typ 35 | From ESP | n/a | |
| TempMin | integer | typ 8 | From ESP | n/a | |
| TempMode | integer | 0,1 | To/From ESP | optional | 0=degC 1=degF |
| TempOffset | float | -10.0 .. +10.0 | To/From ESP | YES | Temperature probe offset |
| Thermostat | int | 0,1 | To/From ESP | YES | |
| ThermostatMethod | int | 0,1,2 | To/From ESP | YES | 0: Conventional 1: User deadband 2: Linear Hz |
| ThermostatOvertemp | int | 0, 2..10 | To/From ESP | YES | Cyclic mode Shutdown (suspend) heater if this much over set point. 0 => disabled Deprecated |
| ThermostatUndertemp | int | -20..0 | To/From ESP | YES | Cyclic mode Restart heater if this much below set point Deprecated |
| ThermostatWindow | float | 0.2 ... 10.0 | To/From ESP | YES | degC span of thermostat window |
| TimerConflict | integer | timer ID | To/From ESP | TO: test nominated timer FROM: timer in conflict |
|
| TimerDays | string | # Mon,Tue,Wed,Thu,Fri,Sat,Sun,Next | To/From ESP | YES | # = index 1..14 |
| TimerRefresh | integer | 1 | To/From ESP | req/set timer info | |
| TimerRepeat | string | # 0,1 | To/From ESP | YES | # = index 1..14 |
| TimerStart | string | # HH:MM | To/From ESP | YES | # = index 1..14 |
| TimerStop | string | # HH:MM | To/From ESP | YES | # = index 1..14 |
| TQuery | integer | 1..14 | To ESP | no | ask for timer params for indicated timer |
Challenge/response sets
MQTT
| Name | Value Type | Typical Values | Direction | Require NVsave | Note |
|---|---|---|---|---|---|
| MQuery | int | 1 | To ESP | n/a | request MQTT params from ESP |
| Name | Value Type | Typical Values | Direction | Require NVsave | Note |
|---|---|---|---|---|---|
| MEn | int | 0,1 | To/From ESP | YES | MQTT enable |
| MHost | string | var | To/From ESP | YES | MQTT server address |
| MPasswd | string | var | To/From ESP | YES | MQTT password |
| MPort | int | var | To/From ESP | YES | MQTT server port |
| MUser | string | var | To/From ESP | YES | MQTT username |
IP communications
| Name | Value Type | Typical Values | Direction | Note |
|---|---|---|---|---|
| IQuery | int | 1 | To ESP | n/a |
| Name | Value Type | Typical Values | Direction | Note |
|---|---|---|---|---|
| IP_AP | string | var | From ESP | AP mode IP address |
| IP_APMAC | string | var | From ESP | AP mode MAC address |
| IP_STA | string | var | From ESP | STA mode IP address |
| IP_STAMAC | string | var | From ESP | STA mode MAC address |
| IP_STASSID | string | var | From ESP | STA mode host AP name |
| IP_OTA | int | 0,1 | From ESP | OTA mode enabled |
System Query
| Name | Value Type | Typical Values | Direction | Require NVsave | Note |
|---|---|---|---|---|---|
| SQuery | int | 1 | To ESP | n/a | request system information from ESP |
| Name | Value Type | Typical Values | Direction | Require NVsave | Note |
|---|---|---|---|---|---|
| Time | string | HH:mm:ss | To/From ESP | no | |
| Date | string | dd/mm/yyyy | To/From ESP | no | |
| DateTime | string | dd/mm/yyyy HH:mm:ss | To/From ESP | no | |
| UpTime | integer | var | From ESP | seconds since last reboot | |
| SysVer | string | var | From ESP | Release version stamp | |
| SysDate | string | var | From ESP | Build date of release | |
| SysFreeMem | integer | var | From ESP | free memory, bytes |
Notes on timer commands
Up to 14 timers are allowed by the ESP32 firmware.
There are however only simple JSON names used, not being adorned with numerics.
This is mainly done to better support App Inventor and the Bluetooth app when decoding received JSON names. The timer associated in the command is instead identified as the first numeric in the following string Value field.
eg: {"TimerStart":"XX HH:MM}, where XX is the timer identifier
The common Names used for the 14 timer parameter sets are TimerStart, TimerStop, TimerRepeat & TimerDays.
A couple of extra commands are used to validate the timer programming, guarding against conflicts.
TimerConflict & TimerRefresh.
After defining and sending a new timer definition, TimerConflict must be sent from a JSON client, the Value being the new timer we have defined and need to test against all others.
If the times and days of the nominated timer conflict with any other timer, the ESP32 will send back TimerConflict, this time with the Value being the detected timer that is conflict.
If a conflict does occur, the nominated timer is disabled by the ESP32 - removing the immediate conflict without changing the times chosen. The timer can then be revised by the client. Likewise, the changed Timer status will be reflected back to the client via JSON as well.
TimerRefresh is used to request a complete update of the timer information by a client, or by the ESP32 to say it has delivered all the timer information. The client can use this JSON message to only update the GUI etc once, not upon every element being sent!