Skip to main content

2. Connecting to a sensor

One key objective when setting up connection between a sensor and Visamic is that the relationship be realistic according to the speed capabilities of data-generation, network speed and server-response for visualisation. A wide area connection will, by nature, have more implicit lag than a local connection. The public Visamic server is resource-limited. Where offering up the means to connect and work with your data pay some heed please to some of the practical limitations that may exist.

Supported sensors#

Visamic web currently supports the connection of MQTT sensor devices only. There are multiple useful tools to experiment with MQTT but our preferences are:

  • Mosquitto's offcial command line clients. mosquitto_pub to publish messages on a topic and mosquitto_sub to subscribe to a topic and print the received messages.
  • MQTTBox Chrome app, available here.

Configuring an MQTT sensor#

The sensor may use any broker as its connection hub to Visamic. Visamic offers its own, secure MQTT server as a broker for your use or you may choose your own broker if you wish. This section describes the setup of both options. Connection to a sensor is made via the Visamic Inputs page.

The Input dialogue screen#

To setup connection to a sensor you should select "Inputs" from the top menu of the Visamic Homepage. It will open the Inputs page listing any Inputs already configured and offering up the button entitled New for you to add a new Input. Clicking that will make the following dialogue appear:

image

You can choose the secure Visamic broker or any external broker of your choice.

Visamic broker#

Our internal broker uses authentification and encrypts all the information with MQTT over TLS.
You can specify a topic but not a username&password. Check the "user name" in the "connector" after creating your input. That's the user name to be used to publish to that topic:

image

The password is the same you used to login the web app.
The userName and password can't be modified.

Certificate#

Visamic broker uses the publicly available certificate from Let's Encypt.
This certificate must be used at the moment of publication of the MQTT topic.

Test Visamic broker#

Save the certificate above as a .pem file (ie, visamic.pem).
In a terminal, subscribe to the topic you created with the username you got at the step above and the password you used to login the web app:

mosquitto_sub -u <username> -P <password> -h visamic.com -t <topic> --cafile certs/visamic.pem

In a different terminal, publish a message to that same topic using the same credentials and certificate:

mosquitto_pub -u <username> -P <password> -h visamic.com -t <topic> --cafile certs/visamic.pem -m "Hello Visamic"

image

The "Hello world" message should be received at the terminal where you ran mosquitto_sub command, confirming the encrypted message has been sent to Visamic's broker:

image

This is just a "Hello World" connection example. To show data in a dashboard you'll need to configure the attributes and to send messages using JSON Payload format. Both requirements are explained below.

External broker#

Using an external broker, you'd need to manually specify the broker's url and port.
You'd also need to specify a username and password if you want the connection to be authentified. Remember not doing so in production without activating TLS.

image

Test external broker#

We recommend the use of a publicly available mosquitto broker if you wish to run some simple tests without requiring to setup security information for your MQTT packet-transfer. An example is the mosquitto.org server, test.mosquitto.org.

Unencrypted, Unauthenticated#

The values for this setup dialogue would be:

  • broker: test.mosquitto.org
  • port: 1883
  • topic: your_topic (this topic name should match the topic that is used when publishing)
  • TLS: Off

We are running an "unencrypted, unauthenticated" test source here with a few attributes. You can connect if you'd like to try it:

  • broker: test.mosquitto.org
  • port: 1883
  • topic: various2021
  • attributes: PZ, TMP, LT, ACC (all numeric)
  • TLS: Off

Unencrypted, Authenticated#

The values for this setup dialogue would be:

  • broker: test.mosquitto.org
  • port: 1884
  • username: rw
  • password: readwrite
  • TLS: Off
  • topic: your_topic (this topic name should match the topic that is used when publishing)

Encrypted, Authenticated#

The values for this setup dialogue would be:

  • broker: test.mosquitto.org
  • port: 8885
  • username: rw
  • password: readwrite
  • TLS: On
  • topic: your_topic (this topic name should match the topic that is used when publishing)

JSON Payload format#

Use the json format described here to wrap your sensor data as a payload: Reference/JSON. Note that the u, v and t values in the json examples coincide with the default payload variables used for field names in the connector configuration dialogue.

Attributes#

Once you have defined the connection, save the Input and click on the 'Edit' button to open it for further configuration. Click on the Attributes button to add/edit the attributes.

Definition of the attributes means defining what fields of the json payload you wish to include in the extraction of data. Once included, attributes will become available to view in realtime and/or save to the retain data table.

image

The attribute names you add should match the names defined in the json payload arriving from your sensor.