Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "SensiNact/Bridge MQTT"
(3 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
== Description == | == Description == | ||
− | This bridge allows | + | This bridge allows sensinact to subscribe to a topic, and materialize a sensinact device based on this topic messages. The devices will be display just after its configuration (once the ''.cfg'' file is deployed, check below) but the value will be update upon the message arrivals. |
+ | |||
+ | == Sensinact version == | ||
+ | |||
+ | This bridge is available in version ''1.5-SNAPSHOT'' | ||
== Requirements == | == Requirements == | ||
− | * | + | * '''mqtt-sb''' bridge activated (via <code>sensinact -c</code>) |
− | * | + | * A mosquitto server running |
+ | |||
+ | == Capability == | ||
+ | |||
+ | * Create a sensinact provider from a message receveid from a MQTT broker topic. | ||
+ | * Instantiate multiple providers, as many as there are configuration files respecting the pattern "mosquitto-*.cfg", the content format example can be seen below | ||
+ | * Pre-process the message content from the MQTT topic, check the section about <code>processors</code> | ||
+ | |||
+ | == How to instantiate == | ||
+ | |||
+ | === Declarative file === | ||
+ | |||
+ | The declarative file allow you to create at runtime a device mapped to a mosquitto topic. According to the <code>topic</code> information added in the file (that will be explained below) you will have a device connected directly to your MQTT broker topic. | ||
+ | |||
+ | In order to create the instance of your device inside sensinact platform you have to create a file that respect the certain pattern <code>mqtt-*.cfg</code> where <code>*</code> can be any string that identify your rule, this will be assigned as your OSGi service PID (for more details check felix ''Configuration Manager''). This configuration file '''MUST''' be deployed in the directory ''$SENSINACT''HOME/cfgs_. | ||
+ | |||
+ | The fields in this file are define as in a regular property file, that by definition contains a list of <code>key</code> and <code>values</code> pairs separated by <code>=</code>. The allowed fields are specified in the list in BNF extended format below . | ||
+ | |||
+ | <pre>id=ALPHA; mandatory | ||
+ | host=ALPHA;default=127.0.0.1 | ||
+ | port=ALPHA;default=1883 | ||
+ | protocol=["ssl"|"tcp"];default=tcp | ||
+ | topic=ALPHA; mandatory | ||
+ | topic.type=["mqtt"|"smarttopic"];default=mqtt | ||
+ | processor=([PROCESSOR["$"[PROCESSOR_EXPRESSION]][","])* | ||
+ | location.latitude=DIGIT | ||
+ | location.longitude=DIGIT | ||
+ | auth.username=ALPHA | ||
+ | auth.password=ALPHA | ||
+ | discovery.firstMessage=["false"|"true"];default=false</pre> | ||
+ | Some processors do not require a PROCESSOR_EXPRESSION, refer to the processor specific topic to get more details | ||
+ | |||
+ | One example of file (named <code>mqtt-1.cfg</code>) content is shown below: | ||
+ | |||
+ | <pre class="text">id=counter | ||
+ | topic=/camera</pre> | ||
+ | === SmartTopic === | ||
+ | |||
+ | Using regular <code>topic</code> you can only attach one device to one topic and you cannot define the service and resource name in which this information will be attached. For this reason the smarttopic was created, its is an language inside a regular MQTT topic that allows the user to specify which portion of the topic will be considered as provider, which as service and so on. | ||
+ | |||
+ | In smarttopic only the <code>{provider}</code>tag is mandatory, case <code>service</code> or <code>resource</code> are not specified the values <code>info</code> and <code>value</code> will be adopted. You can also indicate the value defined for your sensinact devices in the topic using the tag <code>{value}</code>, case this tag is not present the MQTT message will be used as the value of your device. | ||
+ | |||
+ | The supported tags for a ''smarttopic'' are: | ||
+ | |||
+ | <pre>{provider} | ||
+ | {service} | ||
+ | {resource} | ||
+ | {value}</pre> | ||
+ | One example of smarttopic declaration is: | ||
+ | |||
+ | <pre>id=thingsnetworkdevicediscovery | ||
+ | topic.type=smarttopic | ||
+ | topic=+/devices/{provider}/up | ||
+ | host=eu.thethings.network | ||
+ | auth.username=cea-wise-iot | ||
+ | auth.password=ttn-account-xxxIGBKAJtVg_Q1LyMOOqNQPjxxxx4</pre> | ||
+ | You can use the same mechanism of ''processor'' by declaring <code>processor=</code> property in this very same file. | ||
+ | |||
+ | === MQTTRuntime service === | ||
+ | |||
+ | Allow during the gateway runtime to publish the configuration necessary to create a device attached to a topic by passing the file configuration deployment. | ||
+ | |||
+ | TBD | ||
+ | |||
+ | === Annotation === | ||
+ | |||
+ | TBD | ||
+ | |||
+ | == Processors == | ||
+ | |||
+ | <code>Processors</code> are functions that can be chained one after another, each processor receive an <code>input</code> and produces an <code>output</code>; and an output of a processor can serve as an input of another; this chaining can be performed as many time as you need. | ||
+ | |||
+ | Notice that the execution of each processor is performed according to the order in which it appears in the declaration. | ||
+ | |||
+ | === json === | ||
+ | |||
+ | This file receive as input a content in JSON format, and it can output one of the items present in any level of this JSON, and to identify which element of the JSON formmated ''input'' should be selected you use a ''selector''. ''Selector'' is how you specify the element you want to select. | ||
+ | |||
+ | For instance assume the input <code>ex-01</code> as example, you can select the the name of the library with the expression <code>json$store.name</code> thus the result will be <code>mylibrary</code>, and this can be performed in several levels. | ||
+ | |||
+ | INPUT <code>{"store":{"name":"mylibrary","address":"rue des martyrs","bestseller":["Book1","Book2", "Book3"]}}</code> | ||
+ | |||
+ | PROCESSOR ''json'' | ||
+ | |||
+ | PROCESSOR_EXPRESSION <code>store.name</code> (if you use this with configuration file you add <code>processor=json$store.name</code>) | ||
+ | |||
+ | OUTPUT <code>mylibrary</code> | ||
+ | |||
+ | === array === | ||
+ | |||
+ | INPUT <code>["one","two","three"]</code>(json array string) | ||
+ | |||
+ | PROCESSOR ''array'' | ||
+ | |||
+ | PROCESSOR_EXPRESSION <code>1</code> (the item index) | ||
+ | |||
+ | OUTPUT <code>two</code> | ||
+ | |||
+ | === base64 === | ||
+ | |||
+ | INPUT <code>c3VycHJpc2Uh</code>(base64 encoded string) | ||
+ | |||
+ | PROCESSOR ''base64'' | ||
+ | |||
+ | PROCESSOR_EXPRESSION ` ` (empty) | ||
+ | |||
+ | OUTPUT <code>surprise!</code> | ||
+ | |||
+ | === urlencode === | ||
+ | |||
+ | INPUT <code>http%3A%2F%2Fcea.fr%3Fname%3DFeuer%20Bach%26theme%3DPhilosophie</code>(url encoded string) | ||
+ | |||
+ | PROCESSOR ''urlencode'' | ||
+ | |||
+ | PROCESSOR_EXPRESSION ` `(empty) | ||
+ | |||
+ | OUTPUT <code>http://cea.fr?name=Feuer Bach&theme=Philosophie</code> | ||
+ | |||
+ | === toString === | ||
+ | |||
+ | Default filter, that display the string representation of the Object used in the backend | ||
+ | |||
+ | === toInteger === | ||
+ | |||
+ | ''TBC'' | ||
+ | |||
+ | === toFloat === | ||
− | + | ''TBC'' | |
− | + | === plus === | |
− | + | ''TBC'' | |
− | + | === minus === | |
− | + | ''TBC'' | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | === multiply === | |
− | + | ''TBC'' | |
− | + | ||
− | + | ||
− | + | === divide === | |
− | + | ''TBC'' | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
== Limitations == | == Limitations == | ||
− | + | * The topic message is considered as String value, although the SNA generic will perform automatic convertion to numeric types in SNA. Meaning that even String values can use numeric operators as more than, less then, etc. The conversion will be performed automatically in SNA | |
− | * The topic message is considered as | + |
Revision as of 12:54, 15 March 2018
Contents
Description
This bridge allows sensinact to subscribe to a topic, and materialize a sensinact device based on this topic messages. The devices will be display just after its configuration (once the .cfg file is deployed, check below) but the value will be update upon the message arrivals.
Sensinact version
This bridge is available in version 1.5-SNAPSHOT
Requirements
- mqtt-sb bridge activated (via
sensinact -c
) - A mosquitto server running
Capability
- Create a sensinact provider from a message receveid from a MQTT broker topic.
- Instantiate multiple providers, as many as there are configuration files respecting the pattern "mosquitto-*.cfg", the content format example can be seen below
- Pre-process the message content from the MQTT topic, check the section about
processors
How to instantiate
Declarative file
The declarative file allow you to create at runtime a device mapped to a mosquitto topic. According to the topic
information added in the file (that will be explained below) you will have a device connected directly to your MQTT broker topic.
In order to create the instance of your device inside sensinact platform you have to create a file that respect the certain pattern mqtt-*.cfg
where *
can be any string that identify your rule, this will be assigned as your OSGi service PID (for more details check felix Configuration Manager). This configuration file MUST be deployed in the directory $SENSINACTHOME/cfgs_.
The fields in this file are define as in a regular property file, that by definition contains a list of key
and values
pairs separated by =
. The allowed fields are specified in the list in BNF extended format below .
id=ALPHA; mandatory host=ALPHA;default=127.0.0.1 port=ALPHA;default=1883 protocol=["ssl"|"tcp"];default=tcp topic=ALPHA; mandatory topic.type=["mqtt"|"smarttopic"];default=mqtt processor=([PROCESSOR["$"[PROCESSOR_EXPRESSION]][","])* location.latitude=DIGIT location.longitude=DIGIT auth.username=ALPHA auth.password=ALPHA discovery.firstMessage=["false"|"true"];default=false
Some processors do not require a PROCESSOR_EXPRESSION, refer to the processor specific topic to get more details
One example of file (named mqtt-1.cfg
) content is shown below:
id=counter topic=/camera
SmartTopic
Using regular topic
you can only attach one device to one topic and you cannot define the service and resource name in which this information will be attached. For this reason the smarttopic was created, its is an language inside a regular MQTT topic that allows the user to specify which portion of the topic will be considered as provider, which as service and so on.
In smarttopic only the {provider}
tag is mandatory, case service
or resource
are not specified the values info
and value
will be adopted. You can also indicate the value defined for your sensinact devices in the topic using the tag {value}
, case this tag is not present the MQTT message will be used as the value of your device.
The supported tags for a smarttopic are:
{provider} {service} {resource} {value}
One example of smarttopic declaration is:
id=thingsnetworkdevicediscovery topic.type=smarttopic topic=+/devices/{provider}/up host=eu.thethings.network auth.username=cea-wise-iot auth.password=ttn-account-xxxIGBKAJtVg_Q1LyMOOqNQPjxxxx4
You can use the same mechanism of processor by declaring processor=
property in this very same file.
MQTTRuntime service
Allow during the gateway runtime to publish the configuration necessary to create a device attached to a topic by passing the file configuration deployment.
TBD
Annotation
TBD
Processors
Processors
are functions that can be chained one after another, each processor receive an input
and produces an output
; and an output of a processor can serve as an input of another; this chaining can be performed as many time as you need.
Notice that the execution of each processor is performed according to the order in which it appears in the declaration.
json
This file receive as input a content in JSON format, and it can output one of the items present in any level of this JSON, and to identify which element of the JSON formmated input should be selected you use a selector. Selector is how you specify the element you want to select.
For instance assume the input ex-01
as example, you can select the the name of the library with the expression json$store.name
thus the result will be mylibrary
, and this can be performed in several levels.
INPUT {"store":{"name":"mylibrary","address":"rue des martyrs","bestseller":["Book1","Book2", "Book3"]}}
PROCESSOR json
PROCESSOR_EXPRESSION store.name
(if you use this with configuration file you add processor=json$store.name
)
OUTPUT mylibrary
array
INPUT ["one","two","three"]
(json array string)
PROCESSOR array
PROCESSOR_EXPRESSION 1
(the item index)
OUTPUT two
base64
INPUT c3VycHJpc2Uh
(base64 encoded string)
PROCESSOR base64
PROCESSOR_EXPRESSION ` ` (empty)
OUTPUT surprise!
urlencode
INPUT http%3A%2F%2Fcea.fr%3Fname%3DFeuer%20Bach%26theme%3DPhilosophie
(url encoded string)
PROCESSOR urlencode
PROCESSOR_EXPRESSION ` `(empty)
OUTPUT http://cea.fr?name=Feuer Bach&theme=Philosophie
toString
Default filter, that display the string representation of the Object used in the backend
toInteger
TBC
toFloat
TBC
plus
TBC
minus
TBC
multiply
TBC
divide
TBC
Limitations
- The topic message is considered as String value, although the SNA generic will perform automatic convertion to numeric types in SNA. Meaning that even String values can use numeric operators as more than, less then, etc. The conversion will be performed automatically in SNA