SolarFlux API

SolarFlux is a real-time publish/subscribe system based on the MQTT protocol. SolarNodes can publish the data they collect to SolarFlux and then applications can subscribe to receive that data from SolarFlux.

You can try out the SolarFlux Demo app to see the datum being captured by any of your nodes.

Subscribing: MQTT over WebSocket

Applications wishing to subscribe to SolarFlux data can do so by using MQTT over a WebSocket connection. The connection details for the default SolarFlux service are:

Property	Value	Description
URL	wss://flux.solarnetwork.net/mqtt	The WebSocket URL to connect to. This uses TLS encryption.
Client ID	token +	This must start with the same token value used for the Username property, followed by anything. The maximum length is 40 characters.
Username	token	A SolarNetwork security token.
Password	signature	A SolarNetwork V2 signature derived from the token and its associated secret, extended with a Date=D attribute.

Client ID considerations

Some consideration must be given to the Client ID used when connecting to SolarFlux, as they must be unique across all connections to SolarFlux. If you connect to SolarFlux with the same Client ID as one that is already used by another connection, the previous connection will be dropped. Often a randomized Client ID value is appropriate.

The SolarFlux Demo app appends a random UUID (to the required token prefix) for each connection, which is a pretty safe way to ensure no two clients use the same Client ID value for an application where the number of connecting clients is not limited.

If you are developing an application that maintains a stable connection to SolarFlux, then it can be safe to append a simple static value that uniquely identifies the application to the required token prefix.

Password signature values

The MQTT password is a SolarNetwork V2 signature, extended with a Date=D attribute. The request data used to sign the token request must be the following:

Property	Value	Description
Verb	GET	The canonical request HTTP verb.
Path	/solarflux/auth	The canonical request URI.
Host	data.solarnetwork.net	The signed Host header value.
Date		The signed X-SN-Date header value. The date must also be provided in the final signature as a Date=D attribute. See below for more details.

Thus the canonical headers are Host and X-SN-Date and these must both be included as signed headers in the signature.

The final signature value must include an additional Date=D attribute, where D is a Unix epoch value, i.e. the number of seconds since 1 Jan, 1970. Note this is not specified in milliseconds, as is the default in programming languages like Java and JavaScript.

An example MQTT password thus looks like this:

SNWS2 Credential=a09sjds09wu9wjsd9uy2,SignedHeaders=host;x-sn-date,Signature=4d56e33d69300c163f414ee688e9771eabce45d5a425e480a8cc605e97263919,Date=1545069502

The signature can be shortened to include just the Signature and Date attributes, if desired. Thus the following MQTT password is equivalent to the previous example:

Signature=4d56e33d69300c163f414ee688e9771eabce45d5a425e480a8cc605e97263919,Date=1545069502

Also note the the order of the attributes is not significant. Thus the following MQTT password is equivalent to the previous example:

Date=1545069502,Signature=4d56e33d69300c163f414ee688e9771eabce45d5a425e480a8cc605e97263919

Publishing: SolarNode datum

SolarNode devices can post data to SolarFlux via the SolarFlux Upload Service plugin. That plugin posts every datum captured by other plugins up to SolarFlux, using MQTT topics named with the node ID and datum source ID, according to this pattern:

node/N/datum/0/S

In that pattern, N is a node ID and S is a source ID. The 0 in the topic represents the raw aggregation level that SolarNode posts these datum messages at. Note that any leading / in a source ID is stripped from the topic name.

Example topics look like:

node/1/datum/0/Meter
node/2/datum/0/Building1/Room1/Light1
node/2/datum/0/Building1/Room1/Light2

Messages are published with the MQTT retained flag set, which means the most recently published datum is saved by SolarFlux. When an application subscribes to a topic it will immediately receive any retained message for that topic. In this way, SolarFlux will provide a "most recent" snapshot of all datum across all nodes and sources.