This project provides SolarNode plugin that posts datum captured by other SolarNode plugins to a SolarFlux-compatible MQTT server.

The plugin is meant for developers and can be manually installed.

Once installed, a new SolarFlux Upload Service component will appear on the Settings page on your SolarNode. Click on the Manage button to configure services. You'll need to add one configuration for each SolarFlux server you want to upload data to.

Each datum message is published as a CBOR encoded indefinite-length map by default. 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.

Here's an example datum message, expressed as JSON:

{
  "_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
}

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.

The source ID 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 source ID log/net/solarnetwork/node/datum/modbus/ModbusDatumDataSource.

The datum stream consists of the following properties:

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.

Host

The URL to the MQTT server to use. Use mqtts for a TLS encrypted connection, or mqtt for no encryption. For example: mqtts://influx.solarnetwork.net:8884.

Username

For influx.solarnetwork.net:8884 this should be solarnode.

Password

SolarNode will provide its X.509 certificate on TLS connections, so a password might not be necessary. For influx.solarnetwork.net:8884 this is the case, so no password should be configured.

Exclude Properties

You can exclude all internal datum properties like _DatumType with an expression like _.*.

Required Mode

If you would like the ability to control when data is published to SolarFlux you can configure an operational mode, and only when that mode is active will data get published to SolarFlux.

Retained

By default this plugin sets the retained flag on each MQTT message. This benefints clients as when they connect and subscribe to datum topics they will immediately receive the most recently published message instead of having to wait for SolarNode to publish a new message.

Each component can define any number of filters, which are used to restrict the frequency at which individual datum sources are posted to SolarFlux, and/or restrict which properties of the datum are posted. This 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 also configure a Datum Encoder to encode the MQTT message with. 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.

⚠️ Note that all filters are applied in the order they are defined, and then the first filter with a Datum Encoder configured that matches the filter's Source ID pattern will be used to encode the datum.

Each filter configuration contains the following settings:

⚠️ WARNING: the datum sourceId and created properties will be affected by the property include/exclude filters! If you define any include filters, you might want to add an include rule for ^created$. You might like to have sourceId removed to conserve bandwidth, however, given that value is part of the MQTT topic the datum is posted on and thus redundant.

By default if the connection to the configured SolarFlux MQTT 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 SolarIn 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.