SolarIn MQTT

SolarIn also accepts data via the MQTT protocol. SolarNode devices can integrate via MQTT by installing the MQTT Upload plugin. This guide describes how SolarIn uses the MQTT protocol.

Connection requirements

SolarIn/MQTT requires a SSL connection that uses a SolarNode issued X.509 client certificate for authentication. Here are the required MQTT connection properties:

Property	Value	Description
URL	mqtts://queue.solarnetwork.net:8883	The MQTT URL to connect to. This uses TLS encryption.
Client ID	node ID	The ID of the SolarNode posting data. The ID must match the UID attribute of the X.509 client certificate.
Username	-	No username is used.
Password	-	No password is used.

Datum messages

Datum are posted via a MQTT topic that includes the node ID, according to this pattern:

node/N/datum

In that pattern, N is a node ID, which must match the value provided via the X.509 client certificate and MQTT Client ID.

Example topics look like:

node/1/datum
node/2/datum

Datum message format

A MQTT datum message must be CBOR encoded, either a General Datum encoding using a map or a Stream Datum encoding using an array.

General Datum encoding

A datum may be encoded as a map that includes the names of all the properties included in the datum. This form results in larger messages than the Stream Datum encoding form, but does not require downloading the datum stream metadata beforehand.

The following properties are required:

Property	Type	Description
created	Number	The datum date as milliseconds since the epoch, typically the time it was captured at.
sourceId	String	The SolarNetwork source ID.
samples	Map	A General Datum, including classifications.

Here is an example general datum message, expressed as JSON:

{
  "created": 1545167905344,
  "sourceId": "Ph2",
  "samples": {
    "i": {
      "apparentPower": 2797,
      "current": 11.800409317016602,
      "phaseVoltage": 409.89337158203125,
      "powerFactor": 1.2999000549316406,
      "reactivePower": -1996,
      "realPower": 1958,
      "voltage": 236.9553680419922,
      "watts": 1958
    },
    "a": {
      "wattHours": 2739874987928
    },
    "t": [
      "overtemp",
      "error"
    ]
  }
}

Stream Datum encoding

A datum may be encoded as a stream datum, which is an array that omits the names of the properties included in the datum. This form results in smaller messages than the General Datum encoding, but requires downloading the datum stream metadata for the datum stream beforehand.

If additional properties are discovered in a datum that are not defined in the datum stream metadata, the General Datum encoding must be used to provide the new property name to SolarNetwork. Once uploaded, the updated datum stream metadata can be downloaded again, which will include the new property, so the stream datum encoding can be used again.

Here is an example stream datum message, expressed as JSON:

[
  1545167905344,
  11992579225817268499,
  12681893233508468787,
  [2797,11.800409317016602,409.89337158203125,1.2999000549316406,-1996,1958,236.9553680419922,1958],
  [2739874987928],
  ["overtemp"],
  ["error"]
]

Instruction acknowledgement messages

Instruction acknowledgement messages are posted via a MQTT topic that includes the node ID, using this pattern:

node/N/instr

In that pattern, N is a node ID, which must match the value provided via the X.509 client certificate and MQTT Client ID.

Example topics look like:

node/1/instr
node/2/instr

Instruction acknowledgement message format

The instruction acknowledgement messages must be CBOR encoded indefinite-length maps. The following properties are required:

Property	Type	Description
__type__	String	Must be the literal string InstructionStatus.
created	Number	The datum date as milliseconds since the epoch, typically the time it was captured at.
instructionId	Number	The instruction ID the node is posting acknowledgement to.
status	String	An instruction status value.

Here's an example instruction acknowledgement message, expressed as JSON:

{
  "__type__": "InstructionStatus",
  "created": 1410064399000,
  "instructionId": 34982379,
  "status": "Completed"
}