33. SolarFlux¶

SolarFlux is the name of a real-time cloud-based service for datum using a publish/subscribe integration model. SolarNode supports publishing datum to SolarFlux and your own applications can subscribe to receive datum messages as they are published.

SolarFlux is based on MQTT. To integrate with SolarFlux you use a MQTT client application or library. See the SolarFlux Integration Guide for more information.

33.1 SolarFlux Upload Service¶

SolarNode provides the SolarFlux Upload Service plugin that posts datum captured by SolarNode plugins to SolarFlux.

33.2 MQTT message format¶

Each datum message is published as a CBOR encoded map by default, to a MQTT topic based on the datum's source ID. This is essentially a JSON object. The map keys are the datum property names. You can configure a Datum Encoder to encode datum into a different format, by configuring a filter. For example, the Protobuf Datum Encoder supports encoding datum into Protobuf messages.

Messages are published with the MQTT retained flag set by default, 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.

{
  "_DatumType": "net.solarnetwork.node.domain.ACEnergyDatum",
  "_DatumTypes": [
    "net.solarnetwork.node.domain.ACEnergyDatum",
    "net.solarnetwork.node.domain.EnergyDatum",
    "net.solarnetwork.node.domain.Datum",
    "net.solarnetwork.node.domain.GeneralDatum"
  ],
  "apparentPower": 2797,
  "created": 1545167905344,
  "current": 11.800409317016602,
  "phase": "PhaseB",
  "phaseVoltage": 409.89337158203125,
  "powerFactor": 1.2999000549316406,
  "reactivePower": -1996,
  "realPower": 1958,
  "sourceId": "Ph2",
  "voltage": 236.9553680419922,
  "watts": 1958
}

33.3 MQTT message topics¶

The MQTT topic each datum is published to is derived from the node ID and datum source ID, according to this pattern:

node/N/datum/A/S

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

33.4 Log datum stream¶

The EventAdmin Appender is supported, and log events are turned into a datum stream and published to SolarFlux. The log timestamps are used as the datum timestamps.

33.4.1 Log datum stream topic mapping¶

The topic assigned to log events is log/ with the log name appended. Period characters (.) in the log name are replaced with slash characters (/). For example, a log name net.solarnetwork.node.datum.modbus.ModbusDatumDataSource will be turned into the topic log/net/solarnetwork/node/datum/modbus/ModbusDatumDataSource.

33.4.2 Log datum stream properties¶

The datum stream consists of the following properties:

33.5 Settings¶

The SolarFlux Upload Service ships with default settings that work out-of-the-box without any configuration. There are many settings you can change to better suit your needs, however.

Each component configuration contains the following overall settings:

For TLS-encrypted connections, SolarNode will make the node's own X.509 certificate available for client authentication.

33.5.1 Filter settings¶

Each component can define any number of filters, which are used to manipulate the datum published to SolarFlux, such as:

• restrict the frequency at which individual datum sources are published
• restrict which properties of datum are posted
• encode the message into something other than CBOR

The filter settings can be very useful to constrain how much data is sent to SolarFlux, for example on nodes using mobile internet connections where the cost of posting data is high.

A filter can configure a Datum Encoder to encode the MQTT message with, if you want to use a format other than the default CBOR encoding. This can be combined with a Source ID pattern to encode specific sources with specific encoders. For example when using the Protobuf Datum Encoder a single Protobuf message type is supported per encoder. If you want to encode different datum sources into different Protobuf messages, you would configure one encoder per message type, and then one filter per source ID with the corresponding encoder.

Each filter configuration contains the following settings:

33.6 Offline message persistence¶

By default if the connection to the SolarFlux server is down for any reason, all messages that would normally be published to the server will be discarded. This is suitable for most applications that rely on SolarFlux to view real-time status updates only, and SolarNode uploads datum to SolarNet for long-term persistence. For applications that rely on SolarFlux for more, it might be desirable to configure SolarNode to locally cache SolarFlux messages when the connection is down, and then publish those cached messages when the connection is restored. This can be accomplished by deploying the MQTT Persistence plugin.

When that plugin is available, all messages processed by this service will be saved locally when the MQTT connection is down, and then posted once the MQTT connection comes back up. Note the following points to consider:

• The cached messages will be posted with the MQTT retained flag set to false.
• The cached messages will be posted in an unspecified order.
• The cached messages may be posted more than once, regardless of the configured Reliabiliy setting.