Skip to main content

Automation Library API

Version 3.8​

All commands to Molecule OS are via a secure proprietary TCP/IP tunnel.

Start HeaderMessage PayloadEnd Header
0102 : Length MSB : Length LSB : Version : Message Format : Message TypeMessageCRC : 0104
Message FormatDescription
0ASCII
1Binary
Message TypeDescription
1Main Module Message
2Reserved
3Data payload
25External - Automation Application
note

ALL examples and commands shown below will only be describing the Message within the payload.

Module Request

Version​

Version: 1ValueDesc
Message Type1Module command
Message Format0ASCII
Command{"TYP":"1","R":"0"}
Success Response{"R":"0","P":"<Version>"}
Failure Response{"R":"0", "E":"1"}
Example
Request{"TYP":"1","R":"0"}
Response{"R":"0","P":"MCom_l:5.55"}

Get IP​

Version: 1ValueDesc
Message Type1Module command
Message Format0ASCII
Command{"TYP":"1","R":"100"}
Success Response{"R":"100","P":"<IP Address>"}
Failure Response{"R":"100", "E":"1"}
Example
Request{"TYP":"1","R":"100"}
Response{"R":"100","P":"192.168.2.209"}

Scan Wifi Network​

Version: 1ValueDesc
Message Type1Module command
Message Format0ASCII
Command{"TYP":"1","R":"101"}
Success Response{"R":"101","S":"1"}
{"R":"101","I":"7","SID":"<SID>","SIG":"<Signal Strength in Db>","EN":"<Security>"}
{"R":"101","S":"0"}
Failure Response{"R":"101", "E":"1"}
Example
Request{"TYP":"1","R":"101"}
Response{"R":"101","S":"1"}
{"R":"101","I":"7","SID":"NETGEAR63","SIG":"-75","EN":"WPA2-PSK"}
{"R":"101","S":"0"}

Set Wifi Parameters​

Version: 1ValueDesc
Message Type1Module command
Message Format0ASCII
Command{"TYP":"1","R":"102","SID":"<SID>","KEY":"<KEY>","EN":"<Security>"}
Success Response{"R":"102","S":"1"}
Failure Response{"R":"102", "E":"1"}
Example
Request{"TYP":"1","R":"102","SID":"NETGEAR63","KEY":"123456","EN":"PSK2"}
Response{"R":"102","S":"1"}

Set Network Parameters​

Version: 1ValueDesc
Message Type1Module command
Message Format0ASCII
Command{"TYP":"1","R":"103","NWT":"1","IP":"<IP>","NMSK":"<Network Mask>","GWAY":"Gateway", "DNS1":"<Primary DNS>", "DNS2":"<Secondary DNS>"}
NWT:1 => Network Type LAN
NWT:2 => Network Type WWAN
Success Response{"R":"103","S":"1"}
Failure Response{"R":"103", "E":"1"}
Example
Request{"TYP":"1","R":"103","NWT":"1","IP":"0164A8C0","NMSK":"FFFF","GWAY":"0101A8C0", "DNS1":"08080808", "DNS2":"08080808"}
Response{"R":"103","S":"1"}

Remote Access​

Version: 1ValueDesc
Message Type1Module command
Message Format0ASCII
Command{"TYP":"1","R":"104","EN":"1","LP":"<Local Port>","LH":"<Local Host>","DP":"<Device Port>","SP":"<Server Port>","CE":"<Close Existing>"}
EN => 1: Enable, 0: Disable
LH => Local hostname to bind to (Optional, default: localhost)
LP => Hex of Local Port (Optional when EN is 0)
DP => Hex of Device Port (Optional, default: 0x16 / port 22 SSH)
SP => Hex of Server Port (Optional when EN is 0)
CE => 1: Close existing tunnel before opening new one, 0: Do not close (Optional, default: 1)
Success Response{"R":"104","S":"1"}
Failure Response{"R":"104","E":"1"}
Example
Request{"TYP":"1","R":"104","EN":"1","LP":"5DC","SP":"F9FC"}
Response{"R":"104","S":"1"}
info

To obtain the LP (Local Port number), send the following command to the remote access server:

  • Server Host: racc.moleculesystems.com.au
  • Server Port: 1880
  • Remote Free Port Request: {"R":"A1"}
  • Remote Free Port Response: {"R":"A","P":"1550"} where 1550 is the allocated free port

Commands should be sent using the MOS Communication Framework format. Use the helper utility MWinUtilsLib.dll.

byte payload = Encoding.ASCII.GetBytes("{\"R\":\"A1\"}");
byte command = MCommand.ConstructMessage(1, MCommand.MMessageType.ModuleCommand, MCommand.MMessagePayloadFormat.ASCII, payload);

AP Mode​

Version: 1ValueDesc
Message Type1Module command
Message Format0ASCII
Command{"TYP":"1","R":"105","EN":"<Enable/Disable>"}
EN => 1: Enable, 0: Disable
Success Response{"R":"105","S":"1"}
Failure Response{"R":"105", "E":"1"}
Example
Request{"TYP":"1","R":"105","EN":"1"}
Response{"R":"105","S":"1"}

Software Add/Update/Delete​

Version: 1ValueDesc
Message Type1Module command
Message Format0ASCII
Command{"TYP":"1","R":"106","F":"<Force>", "PKG":"<Package names (space separated)>"}
F => 1: Force all package update
Optional "D":"1" will delete all specified packages
Success Response{"R":"106","S":"1"}
Failure Response{"R":"106", "E":"1"}
Example
Request{"TYP":"1","R":"106","F":"1","PKG":"mctlPkg"}
Response{"R":"106","S":"1"}

Set Software Auto Update​

Version: 1ValueDesc
Message Type1Module command
Message Format0ASCII
Command{"TYP":"1","R":"107", "PKG":"<Package names (comma separated>"}
Success Response{"R":"107","S":"1"}
Failure Response{"R":"107", "E":"1"}
Example
Request{"TYP":"1","R":"107","PKG":["mctlPkg", "autoPkg"]}
Response{"R":"107","S":"1"}

Get Software Auto Update​

Version: 1ValueDesc
Message Type1Module command
Message Format0ASCII
Command{"TYP":"1","R":"108"}
Success Response{"R":"108","S":"1"}
Failure Response{"R":"108", "E":"1"}
Example
Request{"TYP":"1","R":"108","P":"mctlPkg"}
Response{"R":"108","S":"1"}

Set Device Time Zone​

Version: 1ValueDesc
Message Type1Module command
Message Format0ASCII
Command{"TYP":"1","R":"109", "TN":"<Time Name>","TZ":"<Time zone parameter in tz format>"}
Success Response{"R":"109","S":"1"}
Failure Response{"R":"109", "E":"1"}
ReferenceTZ Variable (GNU C Library)
Example
Request{"TYP":"1","R":"109", "TN":"Australia/Melbourne", "TZ":"EST-10EST,M10.1.0,M4.1.0/3"}
Response{"R":"109","S":"1"}

Sync Device​

Version: 1ValueDesc
Message Type1Module command
Message Format0ASCII
Command{"TYP":"1","R":"111", "TN":"<Time Name>","TZ":"<TZ format>","DID":[...], "AID":[...], "DAPP":[...]}
Success Response{"R":"111","S":"1"}
Failure Response{"R":"111", "E":"1"}
Example
Request{"TYP":"1","R":"111", "TN":"Australia/Melbourne", "TZ":"EST-10EST,M10.1.0,M4.1.0/3", "DID":["20000","20001"], "AID":["1000","1001"], "DAPP":["autopkg mosctlv2pkg","ebrebootpkg"]}
Response{"R":"111","S":"1"}

Download Device Command File​

Version: 1ValueDesc
Message Type1Module command
Message Format0ASCII
Command{"TYP":"1","R":"112", "CNAME":"<Cmd File Reference ID>/<Cmd File Name>"}
Success Response{"R":"112","S":"1"}
Failure Response{"R":"112", "E":"1"}
Example
Request{"TYP":"1","R":"112", "CNAME":"0000000000000001/Cmd.json"}
Response{"R":"112","S":"1"}
info
  • Command files are stored in a temporary location and a reference is sent to the gateway.
  • The gateway downloads the command file from the server and executes it.
  • After processing the file, the gateway uploads the result back to the server.
  • Once the upload succeeds, the gateway posts a success message as the command response.
  • The server removes the temporary download file after receiving the response.
  • The final response is returned to the calling application or site.

Zigbee Request

Version​

Version: 1ValueDesc
Message Type25Zigbee command
Message Format0ASCII
Command{"TYP":"1","R":"0"}
Success Response{"R":"0","P":"<Version>"}
Failure Response{"R":"0", "E":"1"}
Example
Request{"TYP":"1","R":"0"}
Response{"R":"0","P":"MCtrl_l:5.55"}

Pair New Device​

Version: 1ValueDesc
Message Type25Zigbee command
Message Format0ASCII
Command{"TYP":"1","R":"1"}
Success Response{"R":"1","NA":"<Network Address>","IE":"<IEEE Address>","MFG":"<MFG Name>","MOD":"<Model>","EP":[...]}
Failure Response{"R":"1", "E":"1"}
Example
Request{"TYP":"1","R":"1"}
Response{"R":"1","NA":"754f","IE":"3c6a2cfffed036b6","MFG":"OWON","MOD":"CB432", "EP":[{"I":1,"T":9,"C":[0,3,5,6,702]}]}

Unpair Device​

Version: 1ValueDesc
Message Type25Zigbee command
Message Format0ASCII
Command{"TYP":"1","R":"2","NA":"<Network Address>", "F":"<force unpair 1/0>"}
Success Response{"R":"2", "S":"1"}
Failure Response{"R":"2", "E":"1"}
Example
Request{"TYP":"1","R":"2","NA":"754f"}
Response{"R":"2", "S":"1"}

Request Device Info​

Version: 1ValueDesc
Message Type25Zigbee command
Message Format0ASCII
Command{"TYP":"1","R":"3","NA":"<Network Address>", "ITYP":"<Info type>"}
Success Response{"R":"3", "P":"<Info>"}
Failure Response{"R":"3", "E":"1"}

Zigbee Command​

warning

This command is deprecated.

Version: 1ValueDesc
Message Type25Zigbee command
Message Format0ASCII
Command{"TYP":"1","R":"4","NA":"<Network Address>", "P":"<Endpoint>, <Cluster>,<Value>"}
Success Response{"R":"4", "S":"1"}
Failure Response{"R":"4", "E":"1"}
Example
Request{"TYP":"1","R":"4","NA":"754f", "P":"1,6,1"}
Response{"R":"4", "S":"1"}

Zigbee Read Attribute​

Version: 1ValueDesc
Message Type25Zigbee command
Message Format0ASCII
Command{"TYP":"1","R":"5","NA":"<Network Address>", "P":"<Endpoint>, <Cluster>,<Attribute Id>"}
Success Response{"R":"5", "P":"<Attribute Value>"}
Failure Response{"R":"5", "E":"1"}
Example
Request{"R":"5","NA":"754f", "P":"1,201,1c"}
Response{"R":"5", "P":"04"}

Zigbee Set Attribute​

Version: 1ValueDesc
Message Type25Zigbee command
Message Format0ASCII
Command{"TYP":"1","R":"6","NA":"<Network Address>", "P":"<Endpoint>, <Cluster>,<Attribute Id>,<Attribute Value>"}
Success Response{"R":"6", "S":"1"}
Failure Response{"R":"6", "E":"1"}
Example
Request{"R":"6","NA":"754f", "P":"1,201,1c,4"}
Response{"R":"6", "S":"1"}

List Devices​

Version: 1ValueDesc
Message Type25Zigbee command
Message Format0ASCII
Command{"TYP":"1","R":"A"}
Success Response{"R":"A", "P":["<Network Address>-<Mac Address>",...]}
Failure Response{"R":"A", "E":"1"}
Example
Request{"TYP":"1","R":"A"}
Response{"R":"A","P":["754f-002446000011db67"]}

Get Device Status​

Version: 1ValueDesc
Message Type25Zigbee command
Message Format0ASCII
Command{"TYP":"1","R":"A1", "ID": "<Control ID>"} NOTE: "ID" is optional. If not passed, status for all items is returned.
Success Response{"R":"A1","P":[{"ID":"<Network Address>","TYP":"1","STA":[{"EP":"<End Point>","VAL":[...]}]}]}
Failure Response{"R":"A1", "E":"1"}
Example
Request{"TYP":"1","R":"A1"}
Response{"R":"A1","P":[{"ID":"754f","TYP":"1","STA":[{"EP":"1","VAL":[6,1,1]}]}]}

Instantaneous Value Stream​

Version: 1ValueDesc
Message Type25Device command
Message Format0ASCII
Command{"TYP":"1","R":"A0"}
Success Response{"R":"A0", "S":"1"} Start of stream / {"R":"A0", "P":"<value>"} Stream value / {"R":"A0", "S":"0"} End of stream
Failure Response{"R":"A0", "E":"1"}
Example
Request{"TYP":"1","R":"A0"}
Response{"R":"A0", "S":"1"} ... {"R":"A0", "S":"0"}

Modbus, GPIO and External API Request

Pair New Device​

Version: 1ValueDesc
Message Type25Modbus Command
Message Format0ASCII
Command{"TYP":"1","R":"B1", "PT":"<Protocol>", "CNAME":"<Config Reference ID>/<Config Name>","F":"<Force download>"}
Success Response{"R":"B1","CID":"<Control ID>"}
Failure Response{"R":"B1", "E":"1"}
Example
Request{"TYP":"1","R":"B1"}
Response{"R":"B1","CID":"1000"} - response payload varies for device types, see notes below
Protocol Specific Values

Parameters: PT Protocol type (0 = Modbus default), Config Reference ID (max 32 chars), Config Name (max 16 chars), F Force download

MODBUS ("PT":"0") RTU: {"TYP":"1","R":"B1", "PT":"0", "MT":"1", "SID":"<Slave ID>", "CNAME":"...", "F":"..."} TCP/IP: {"TYP":"1","R":"B1", "PT":"0", "MT":"2", "SID":"<Slave ID>", "IP":"<Modbus IP>", "PORT":"<Port>","CNAME":"..."} MT: RTU=1, TCP/IP=2. Slave ID defaults to 1. Modbus IP in big endian hex (192.168.1.24 = 1801A8C0). Port defaults to 502 (0x1FE).

GPIO ("PT":"1") {"TYP":"1","R":"B1", "PT":"1", "NM":"<Pin Name>", "CNAME":"..."} NM = GPIO name from config file

External API ("PT":"2") {"TYP":"1","R":"B1", "PT":"2", "UID":"<Unique ID>", "ETYP":"<API Type>"} ETYP: 1=Enode. DTYP: 10=Storage/Hybrid, 11=PV Inverter, 12=Meter, 13=Thermostat, 14=On/Off Switch

Zigbee ("PT":"3") {"TYP":"1","R":"B1", "PT":"3", "IEEE":"<IEEE address>"} IEEE is optional.

Unpair Device​

Version: 1ValueDesc
Message Type25Modbus Command
Message Format0ASCII
Command{"TYP":"1","R":"B2", "CID":"<Control ID>"}
Success Response{"R":"B2","S":"1"}
Failure Response{"R":"B2", "E":"1"}
Example
Request{"TYP":"1","R":"B2","CID":"1000"}
Response{"R":"B2","S":"1"}

Request Device Info​

warning

This command is currently not implemented.

Version: 1ValueDesc
Message Type25Modbus command
Message Format0ASCII
Command{"TYP":"1","R":"B3","CID":"<Control ID>", "ITYP":"<Info type>"}
Success Response{"R":"B3", "P":"<Info>"}
Failure Response{"R":"B3", "E":"1"}

Update Config​

Version: 1ValueDesc
Message Type25Modbus command
Message Format0ASCII
Command{"TYP":"1","R":"B4","CID":"<Control ID>","CNAME":"<Config Reference ID>/<Config Name>"}
CNAME is optional. If not provided, existing CNAME is used.
Success Response{"R":"B4", "S":"1"}
Failure Response{"R":"B4", "E":"1"}

Set Attributes​

Version: 1ValueDesc
Message Type25Modbus command
Message Format0ASCII
Command{"TYP":"1","R":"B5","CID":"<Control ID>", <Parameters>} See parameter details below.
Success Response{"R":"B5", "S":"1"}
Failure Response{"R":"B5", "E":"1"}
Example
Request{"R":"B5", "CID":"20000","SCOUNT":"3"}
Response{"R":"B5", "S":"1"}
Set Attributes Parameters

ALL: "DATA_MAP":"<Data Map>" Byte 0-1: Sensor Count, Byte 2-9: Bitmask, Byte 9+: Leg config. Bitmask: 0=Usage, 1=Export, 2=Generation, 3=BattCharge, 4=BattDischarge, 5=BattSOC. Example: "DATA_MAP":"01 00000010 00 00 00 00 00 01"

PV Inverter: "MAX_PWR" max rated power (default 3000w), "DEV_FLG" Bit 0=Export Limit, "EXP_LIMIT" export limit (default 0w)

Storage Inverter (plus PV values): "DEV_FLG" Bit 1=Charge on Export, Bit 2=Charge on Generation, "MAX_DCHRG" max discharge % (default 20%), "MAX_CHRG" max charge % (default 100%)

Send Trigger Event​

Version: 1ValueDesc
Message Type25Modbus command
Message Format0ASCII
Command{"TYP":"1","R":"B6","CID":"<Control ID>","FGAP":"<From Epoch>-<To Epoch>"}
FGAP (METER ONLY): From/To Epoch in hex
Success Response{"R":"B6", "S":"1"}
Failure Response{"R":"B6", "E":"1"}
Example
Request{"R":"B6", "CID":"20000","FGAP":"634F62C4-634F6648"}
Response{"R":"B6", "S":"1"}

Send Command​

Version: 1ValueDesc
Message Type25Modbus command
Message Format0ASCII
Command{"TYP":"1","R":"B7","CID":"<Control ID>","CMD":"<Type>","P":"<Payload>"}
- Type 0Reset — Payload: none
- Type 1Switch — Payload: 0=Off, 1=On. Zigbee: endpoint,cluster,value
- Type 2Charge — Payload: Exponent, Charge Value, Duration (seconds)
- Type 3Discharge — Payload: Exponent, Discharge Value, Duration (seconds)
- Type 4Grid Form — Payload: 0=Off, 1=On
- Type 5Set Control Mode — Thermostat: 1=Off, 2=Heat, 3=Cool, 4=Auto
- Type 6Set Temperature — Payload: Temperature in Degree C
Success Response{"R":"B7", "S":"1"}
Failure Response{"R":"B7", "E":"1"}
Example
Request{"R":"B7", "CID":"21000","CMD":"1", "P":"1"}
Response{"R":"B7", "S":"1"}

List Devices​

Version: 1ValueDesc
Message Type25Modbus command
Message Format0ASCII
Command{"TYP":"1","R":"BA"}
Success Response{"R":"BA", "P":["<CID>","<CID n>"]}
Failure Response{"R":"BA", "E":"1"}
Example
Request{"TYP":"1","R":"BA"}
Response{"R":"BA","P":["20000"]}

Set Device Operational Flags​

Version: 1ValueDesc
Message Type25Device command
Message Format0ASCII
Command{"TYP":"1","R":"BB","CID":"<Control ID>", "P":"<Operational flags in hex>"}
Success Response{"R":"BB", "S":"1"}
Failure Response{"R":"BB", "E":"1"}
Example
Request{"R":"BB","CID":"754f", "P":"01"}
Response{"R":"BB", "S":"1"}
FlagBit
DEVICE_OP_FLG_ENABLED0
DEVICE_OP_FLG_SCHEDULE_ENABLED1
DEVICE_OP_FLG_AUTO_MODE_ENABLED2

Set Device Schedules​

Version: 1ValueDesc
Message Type25Device command
Message Format0ASCII
Command{"TYP":"1","R":"BC","CID":"<Control ID>", "P":"<Slot ID>:<Schedule Param>-<Additional Param>"}
Success Response{"R":"BC", "S":"1"}
Failure Response{"R":"BC", "E":"1"}
Example
Request{"R":"BC","CID":"20000", "P":"1:021C0438FF00-000100060000"}
Response{"R":"BC", "S":"1"}

Schedule Param (2 chars per byte): Byte 0-1 Start Time, 2-3 End Time, 4 Day of Week, 5 Schedule Flags. Flags (Inverter/Battery): Bit 0=Fixed charge, Bit 1=Fixed discharge, Bit 2=Max discharge & Load Follow

Additional Param (3x 16-bit): Zigbee: 0-1=Endpoint, 2-3=Cluster, 4-5=Unused. Storage Inverter: 0-1=Multiplier exponent, 2-3=Trigger Load, 4-5=Charge/Discharge watts.

tip

For smart plugs, use Switching Cluster 6 and the relevant endpoint from pairing.

TOU - Time of Use Functions

Add TOU​

Version: 1ValueDesc
Message Type25TOU Command
Message Format0ASCII
Command{"TYP":"1","R":"C1", "TNAME":"<TOU Reference ID>/<TOU Name>","D":"<Set Default>","F":"<Force download>"}
Success Response{"R":"C1","TID":"<TOU ID>"}
Failure Response{"R":"C1", "E":"1"}
Example
Request{"TYP":"1","R":"C1","TNAME":"0000000000000001/SampleTOU.json"}
Response{"R":"CF","TID":"1000"}
info

TOU Reference ID max 32 chars, TOU Name max 16 chars. F=1 forces download even if file exists. D=1 sets as default TOU (only one TOU can be default at a time).

Remove TOU​

Version: 1ValueDesc
Message Type25TOU Command
Message Format0ASCII
Command{"TYP":"1","R":"C2", "TID":"<TOU ID>"}
Success Response{"R":"C2","S":"1"}
Failure Response{"R":"C2", "E":"1"}
Example
Request{"TYP":"1","R":"C2","TID":"1000"}
Response{"R":"C2","S":"1"}

Set TOU Parameters​

Version: 1ValueDesc
Message Type25TOU Command
Message Format0ASCII
Command{"TYP":"1","R":"C3", "TID":"<TOU ID>", "D":"<Set Default>"}
Success Response{"R":"C3","S":"1"}
Failure Response{"R":"C3", "E":"1"}
Example
Request{"TYP":"1","R":"C3","TID":"1000"}
Response{"R":"C3","S":"1"}

Update TOU​

Version: 1ValueDesc
Message Type25TOU Command
Message Format0ASCII
Command{"TYP":"1","R":"C4", "TID":"<TOU ID>", "TNAME":"<TOU Reference ID>/<TOU Name>"}
Success Response{"R":"C4","TID":"<TOU ID>"}
Failure Response{"R":"C4", "E":"1"}
Example
Request{"TYP":"1","R":"C4","TNAME":"0000000000000001/SampleTOU.json"}
Response{"R":"C4","TID":"1000"}

Automation Functions

Add Automation​

Version: 1ValueDesc
Message Type25Automation Command
Message Format0ASCII
Command{"TYP":"1","R":"F1", "ANAME":"<Auto Reference ID>/<Auto Name>","F":"<Force download>"}
Success Response{"R":"F1","AID":"<Automation ID>"}
Failure Response{"R":"F1", "E":"1"}
Example
Request{"TYP":"1","R":"F1","ANAME":"0000000000000001/SampleAuto.acf"}
Response{"R":"BF","AID":"1000"}
info

Auto Reference ID max 32 chars, Auto Name max 16 chars. F=1 forces download even if file exists.

Remove Automation​

Version: 1ValueDesc
Message Type25Automation Command
Message Format0ASCII
Command{"TYP":"1","R":"F2", "AID":"<Automation ID>"}
Success Response{"R":"F2","S":"1"}
Failure Response{"R":"F2", "E":"1"}
Example
Request{"TYP":"1","R":"F2","AID":"1000"}
Response{"R":"F2","S":"1"}

Set Automation Parameters​

Version: 1ValueDesc
Message Type25Automation Command
Message Format0ASCII
Command{"TYP":"1","R":"F3","AID":"1000","PRI":"1","FLG":"0","UVAR":[{"_Var1":"100"}],"GRP":[{"_Group1":["1000","2000"]}]}
PRI: Priority 0-99 (default 99). FLG: Bit 0=Enable. UVAR: user values array. GRP: group order array.
Success Response{"R":"F3","S":"1"}
Failure Response{"R":"F3", "E":"1"}
Example
Request{"TYP":"1","R":"F3","AID":"1000","UVAR":[{"_Var1":"100"}],"GRP":[{"_Group1":["1000","2000"]}]}
Response{"R":"F3","S":"1"}

Update Automation​

Version: 1ValueDesc
Message Type25Automation Command
Message Format0ASCII
Command{"TYP":"1","R":"F4", "AID":"<Automation ID>", "ANAME":"<Auto Reference ID>/<Auto Name>"}
Success Response{"R":"F4","AID":"<Automation ID>"}
Failure Response{"R":"F4", "E":"1"}
Example
Request{"TYP":"1","R":"F4","ANAME":"0000000000000001/SampleAuto.acf"}
Response{"R":"F4","AID":"1000"}

Set Automation Schedules​

Version: 1ValueDesc
Message Type25Device command
Message Format0ASCII
Command{"TYP":"1","R":"FC","AID":"<Automation ID>", "P":"<Slot ID>:<Schedule Param>-<Additional Param>"}
Success Response{"R":"FC", "S":"1"}
Failure Response{"R":"FC", "E":"1"}
Example
Request{"R":"FC","AID":"1000", "P":"1:021C0438FF00-000100060000"}
Response{"R":"FC", "S":"1"}

Schedule Param (2 chars per byte): Byte 0-1 Start Time, 2-3 End Time, 4 Day of Week, 5 Schedule Flags

Data Payload​

VersionTime since 2020 (EPOCH - 1577836800)Data
1 byte4 bytesData

Data​

{
  "PD": [
    {
      "ID": "<Device ID>",
      "TYP": "<1 - Measurement, 2 - Status, 3 - Device specific>",
      "TIM": "<Time in EPOCH from 1 JAN 2020>",
      "USG": "<Usage in Wh>",
      "GEN": "<Generation in Wh>",
      "EXP": "<Export in Wh>",
      "BTCHG": "<Battery charge in Wh>",
      "BTDCHG": "<Battery discharge in Wh>",
      "BTSOC": "<Battery SOC (Integer 1-100)>",
      "BTCHGC": "<Battery charge event count>",
      "BTDCHGC": "<Battery discharge event count>",
      "V1": "<Voltage1 in Volts>",
      "V2": "<Voltage2 in Volts>",
      "V3": "<Voltage3 in Volts>",
      "FZ": "<Frequency in Hz>",
      "MOD": "<HVAC: 1-OFF, 2-HEATING, 3-COOLING, 4-AUTO>",
      "TEMP": "<Temp in Degree C>",
      "STEMP": "<Set Temp in Degree C>",
      "KV": {"<key1>":"<value1>","<key2>":"<value2>"},
      "PV": [
        {
          "ID": "<Power Value ID>",
          "WHP": "<Active energy (Positive) in Wh>",
          "WHN": "<Active energy (Negative) in Wh>",
          "VAHP": "<Apparent energy (Positive) in Wh>",
          "VAHN": "<Apparent energy (Negative) in Wh>",
          "VARHP": "<Reactive energy (Positive) in Wh>",
          "VARHN": "<Reactive energy (Negative) in Wh>",
          "PW": "<Peak active power in Watts>",
          "PVA": "<Peak Apparent power in Watts>",
          "PVAR": "<Peak reactive power in Watts>",
          "I": "<Current in Amps>",
          "PF": "<PowerFactor>"
        }
      ]
    }
  ],
  "ALR": [
    {
      "ID": "<Device ID>",
      "TAGS": "[<Alert>]"
    }
  ]
}

KV Field​

The KV field allows transmission of arbitrary custom data as key-value pairs for device-specific or application-specific data not covered by standard fields.

"KV": {"Key1": "StringValue", "Key2": 50}

String values use quotes, numeric values do not. Any number of pairs may be included. Field is optional.

{
  "ID": "20000",
  "TYP": "3",
  "TIM": "12345678",
  "KV": {"SerialNumber": "SN-00123", "FirmwareVersion": "2.1.4", "SignalStrength": -75}
}
note

KV object will not be present if there are no key-value pairs to report.

Data Type Representation​

FormatUsage
0x prefixHex values
DigitsBase 10 numbers
""Other number representations

Device ID Range​

RangeType
0x1 - 0xffffZigbee
0x10000 - 0x1ffffInternal
0x20000 - 0x2ffffExternal

Alert​

Alerts are sent as a JSON array in the "ALR" parameter.

  • S_<Alert Tag> — system alerts
  • U_<Alert Tag> — user defined alerts

System Alert Definitions: S_COM_1 Intermittent communication issue, S_COM_2 Critical communication issue

note
  • MongoDB Cache contains only the Data segment of the payload.
  • If accumulated values (USG, GEN, EXP, BTCHG, BTDCHG) are null, use the last known value to populate the database field.