Documentation

Connect, send and retrieve data

Install the CLI

infinimesh features a CLI to interact with our API. Install it automatically with our install script:

curl https://raw.githubusercontent.com/infinimesh/infinimesh/master/godownloader.sh | BINDIR=$HOME/bin bash

Please note: Depending on your OS/distribution, it may be necessary to add ~/bin to your PATH. 
After installing, set up the CLI to use our managed SaaS offering by running this command:

inf config set-context saas --apiserver grpc.api.infinimesh.io:443 --tls=true

This adds a context entry to the CLI configuration at ~/.inf/config. TLS is enforced to guarantee secure communication with the API server. Now, you can log into infinimesh. Run inf login and enter your username and password, this requests a token from the API server – your username and password is NOT stored – we take security very seriously.

Creating a device identity

To get started, we will create a device. Please note, every device needs to have an own certificate. At present, infinimesh supports only X509 certificate authentication for devices. Generate a private key for the device:

openssl genrsa -out my-device-1.key 4096

Generate the client certificate (and self-sign it):

openssl req -new -x509 -sha256 -key my-device-1.key -out my-device-1.crt -days 365

Authorize your new created device with infinimesh IoT

A namespace for your user will be automatically created – the name of the namespace is your username. To show the namespace(s) use the list command:

inf namespace list

Register the device in infinimesh’s device registry:

inf device create test-dev-1 --cert-file my-device-1.crt

The device is registered and the fingerprint of the certificate is returned. The platform uses this fingerprint to uniquely identify your device. To check your devices and get the UID use the list command:

inf device list
ID   NAME        ENABLED
0x8a test-dev-1  value:true

Now your device has been securely and successfully registered. Please note that the ID will be different as in that example.

Send data from a device to infinimesh

To simulate a device, we use the mosquitto_pub client. You can use any MQTT client, e.g. Eclipse paho as well as Microsoft Edge on RaspberryPI, Yocto MQTT layers or Ubuntu Core based snaps. We use sometimes MQTTBox  (http://workswithweb.com/html/mqttbox/installing_apps.html) to demonstrate and test.

inf namespace list

Register the device in infinimesh’s device registry:

mosquitto_pub --cafile /etc/ssl/certs/ca-certificates.crt --cert my-device-1.crt \
--key my-device-1.key -m '{"abc" : 1337}' -t "devices/state/reported/delta" \
 -h mqtt.api.infinimesh.io --tls-version tlsv1.2 -d -p 8883

Note: you will most likely need to adjust the –cafile flag to the path to the CA certificates on your system. This is OS specific.

You will see the following output:

Client mosqpub|3396-thinkpad sending CONNECT
Client mosqpub|3396-thinkpad received CONNACK (0)
Client mosqpub|3396-thinkpad sending PUBLISH (d0, q0, r0, m1, 'devices/0x8a/state/reported/delta', ... (14 bytes))
Client mosqpub|3396-thinkpad sending DISCONNECT

The data has been sent successfully to the platform. To send more than one value per API call you can use JSON arrays in any complexity (https://www.w3schools.com/js/js_json_arrays.asp).

Read device data from the platform

We managed to send data from a device to the platform. Now let’s read back the device data from infinimesh! You can do this via gRPC or HTTP API. The simplest way is with the CLI (which uses gRPC).

inf state get 0x8a

Replace 0x8a with the ID of your device. The output will look like this:

Reported State:
Version: 2
Timestamp: 2019-03-30 20:53:41.844158131 +0100 CET
Data:
{
"abc": 1337
}
Desired State: <none>
Configuration: <none>

In this case, the device sent a datapoint abc with the value 1337 at 20:53:41.

Send states from the platform to the device

Sending states (desired states) to a device is very simple. You only need to know the deviceID. Use the API, or just the CLI.

inf state set 0x8a test_works

Note: Replace 0x8a with the ID of your device.

This sends the state test_works to the device. Note that repeatedly sending the same state does not trigger a new message every time. Only changes are sent to the device. Once the state has been sent, you can inspect it on the server by running:

inf state get 0x8a

The state is visible in the desired section.

Thank you

Many thanks for your time and if you have any questions don’t hesitate to get in touch with us! We are grateful for any improvements to the platform or this documentation, just send us a PR.

We believe that smart and connected devices bring our society forward. Take IoT under your control.