Skip to main content

MQTT

Yggio hosts an MQTT broker. It can be used to subscribe to iotnode-updates and update some types of devices.

As a data consumer​

Every node that has at least one MQTT-channel connected to it will publish values under the topic: yggio/output/v2/[ID]/iotnode/[iotnodeId]. Where [iotnodeId] is the ID of the iotnode, and [ID] is one of the following: userId of Yggio-user, clientAppId or basicCredentialsSetId. It is possible to subscribe to yggio/output/v2/[ID]/# to get data for all iotnodes. You can find more information on how to create a channel here.

userId and clientAppId (Keycloak)​

Authentication is done by either using User ID and token, or Client App ID (OpenId Relying Party client_id) and token (client credentials).

A user access token can be acquired through the normal login request. It can be found in our Swagger-documentation.

A client app access token, a.k.a. client credentials, is retrieved by calling our authorization-server (Keycloak) directly. Below is a curl command you can modify and use. Also, you can find more information about the request in Keycloaks documentation here.

curl -sS --location --request POST 'http://staging.yggio.net/auth/realms/yggio/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode "client_id=[YOUR CLIENT_ID]" \
--data-urlencode "client_secret=[YOUR CLIENT_SECRET]" \
--data-urlencode 'grant_type=client_credentials'

Now you can subscribe to your topic with your ID and token. An example mosquitto command would look like this:

mosquitto_sub -h mqtt.staging.yggio.net -t "yggio/output/v2/675fc0dd-9e9f-4e9e-b041-827eefcd46a0/#" -u 675fc0dd-9e9f-4e9e-b041-827eefcd46a0 \
-P eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJOWTJZVE9tSVBXekRWT1pTT2k2RXBUaEhfMlVmcVJtRko2R1NkTUYwTENrIn0.eyJleHAiOjE2MjIxMjYyODcsImlhdCI6MTYyMjEyMjY4NywiYXV0aF90aW1lIjowLCJqdGkiOiI3YjM5M2I5MC1hMTg5LTQ0M2MtOTk0My05NTI4MjYzZTVkZGMiLCJpc3MiOiJodHRwOi8va2V5Y2xvYWsubG9jYWwueWdnaW8vYXV0aC9yZWFsbXMveWdnaW8iLCJhdWQiOiJ5Z2dpby1zZXJ2aWNlcyIsInN1YiI6IjY3NWZjMGRkLTllOWYtNGU5ZS1iMDQxLTgyN2VlZmNkNDZhMCIsInR5cCI6IklEIiwiYXpwIjoieWdnaW8tc2VydmljZXMiLCJzZXNzaW9uX3N0YXRlIjoiZDliZTA4MjMtNDU5MS00MWMwLTk4N2UtZjNiNWRmMTlkN2NiIiwiYXRfaGFzaCI6Ik4tdjNaNjNtWjZhbTlrelRJUENwMXciLCJhY3IiOiIxIiwiZW1haWxfdmVyaWZpZWQiOnRydWUsIm5hbWUiOiJGaWxpcCBIYXJhbGQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ0ZXN0IiwiZ2l2ZW5fbmFtZSI6IkZpbGlwIiwiZmFtaWx5X25hbWUiOiJIYXJhbGQiLCJlbWFpbCI6ImZpbGlwLmhhcmFsZEBnbWFpbC5jb20ifQ.ZyiVA88RGZ0dWGkjJA3_9UvbK-oeUoes2xciWpYEc1rmOnd7W39QypMM1yGcdPqGLXmxBAn-hBguQjVKSwtRNqfaCiLVGufppJsHB1AsMrWj7_HIht0DoyIAX6G62ePAF4ifaEDMYVlBih5c330OBWJGnlVtVGvEEmDNJ1DKU_zfQ77F8krN8yEobUHxPAPuRch0Dqi7_YBFlUoOGfcO-ovPG7lltOmCX1oW7zFrDcITrLPAJuhRMPLsx6B9Af2i0nAMQSgVTFNVpKuH54chvZYj_3MbraeLrIPXNPkLUImq4qdHfnU1z6KWfu4FQ9nakX_lS6qI2ttW5_yh625ryQ

basicCredentialsSetId​

Sometimes it's not possible for the client to refresh the token when subscribing, then you can instead connect the channel to a "basic credentials set". Below is an example with a basicCredentialsSet and a working mosquitto_sub.

// basicCredentialsSet
{
  _id: '123456789abcdefg'
  username: 'my-device-name',
  password: 'very-very-super-secret-password'
}
mosquitto_sub -h mqtt.staging.yggio.net -t "yggio/output/v2/123456789abcdef/#" -u my-device-name -P very-very-super-secret-password

As a data provider​

Yggio has an MQTT-integration which enables devices, or cloud services, to publish data to Yggio. In order for this to be secure, it is required to have both a "basic credentials set" and a "reserved mqtt topic" set up. Once you have that, you can start publishing data on yggio/generic/v2/[your-sub-topic-here]/[optionally-any-other-sub-topic-here]*. The payload is required to be JSON.

The reserved MQTT topic is used as identifier for the created entity in Yggio. Depending if there is an integration made for the device protocol or not, this identifier can be used differently.

*If you want to connect a MQTT-device that is already supported by Yggio. Please go to the subsection "Yggio Supported MQTT Devices" below. Or click here.

Generic​

For generic devices the reserved MQTT topic is used as an identifier for the created entity in Yggio. And the identifier will be stored on entity.secret. A user can, before or after the data stream has started, "claim" the entity in the Yggio UI. By entering the secret, i.e. reservedMqttTopic.topic when onboarding the device. The entity will have the same access rights as the basicCredentialsSet.

Examples​

Below you find examples of basicCredentialsSets, reservedMqttTopics and their resulting valid MQTT-publishes.

Ex 1 - one simple device​
DB-entities​
// basicCredentialsSet
{
  _id: '123456789abcdefg'
  username: 'my-device-name',
  password: 'very-very-super-secret-password'
}
// reservedMqttTopic
{
  topic: 'yggio/generic/v2/any/unique/topic/321',
  basicCredentialsSetId: '123456789abcdefg'
}
valid publishes (mosquitto-syntax)​
mosquitto_pub -h mqtt.staging.yggio.net -u "my-device-name" -P "very-very-super-secret-password" -t "yggio/generic/v2/any/unique/topic/321" -m '{"health":"running"}'
mosquitto_pub -h mqtt.staging.yggio.net -u "my-device-name" -P "very-very-super-secret-password" -t "yggio/generic/v2/any/unique/topic/321/stats" -m '{"battery":100, "antennaStatus": "sending"}'
mosquitto_pub -h mqtt.staging.yggio.net -u "my-device-name" -P "very-very-super-secret-password" -t "yggio/generic/v2/any/unique/topic/321/temperature" -m '{"value":22}'

All three of the above publishes will result in the update, or creation, of the below iotnode. It's important to note that publishing to a sub topic does not create a new iotnode.

{
  _id: 'abababababa1212121212'
  secret: 'yggio/generic/v2/any/unique/topic/321',
  health: "running",
  stats: {
    antennaStatus: "sending",
    battery: 100
  },
  temperature: {
    value: 22
  }
}
Ex 2 - gateway- or "cloud"- with sub-nodes​
DB-entities​
// basicCredentialsSet
{
  _id: '123456789abcdefg'
  username: 'my-gateway-name',
  password: 'very-very-super-secret-password'
}
// reservedMqttTopic
[
  {
    topic: 'yggio/generic/v2/any/unique/gatewaytopic/4321',
    basicCredentialsSetId: '123456789abcdefg'
  },
  {
    topic: 'yggio/generic/v2/any/unique/gatewaytopic/4321/devices/1',
    basicCredentialsSetId: '123456789abcdefg'
  },
  {
    topic: 'yggio/generic/v2/any/unique/gatewaytopic/4321/devices/2',
    basicCredentialsSetId: '123456789abcdefg'
  }
]
valid publishes (mosquitto-syntax)​
mosquitto_pub -h mqtt.staging.yggio.net -u "my-gateway-name" -P "very-very-super-secret-password" -t "yggio/generic/v2/any/unique/gatewaytopic/4321" -m '{"health":"running"}'
mosquitto_pub -h mqtt.staging.yggio.net -u "my-gateway-name" -P "very-very-super-secret-password" -t "yggio/generic/v2/any/unique/gatewaytopic/4321/devices/1" -m '{"lightSwitch":on}'
mosquitto_pub -h mqtt.staging.yggio.net -u "my-gateway-name" -P "very-very-super-secret-password" -t "yggio/generic/v2/any/unique/gatewaytopic/4321/devices/2" -m '{"lightSwitch":off}'

All three of the above publishes will result in the update, or creation, of the below entities.

{
  _id: 'aaaaaaaaaaa111111111111'
  secret: 'yggio/generic/v2/any/unique/gatewaytopic/4321',
  health: "running",
}
{
  _id: 'bbbbbbbbbbbb22222222222'
  secret: 'yggio/generic/v2/any/unique/gatewaytopic/4321/devices/1',
  lightSwitch: "on",
}
{
  _id: 'cccccccccccc33333333333'
  secret: 'yggio/generic/v2/any/unique/gatewaytopic/4321/devices/2',
  lightSwitch: "off",
}

It's worth mentioning, that a publish to e.g. .../devices/3 would not create a new entity. But instead update the gateway, in this case. This is because there has not been a "reservation" for that topic, i.e. no reservedMqttTopic exists.

So, a publish like this...

mosquitto_pub -h mqtt.staging.yggio.net -u "my-gateway-name" -P "very-very-super-secret-password" -t "yggio/generic/v2/any/unique/gatewaytopic/4321/devices/3" -m '{"lightSwitch": "on"}'

...would update the entity from this...

{
  secret: 'yggio/generic/v2/any/unique/gatewaytopic/4321',
  health: "running",
}

...to this...

{
  _id: 'aaaaaaaaaaa111111111111'
  secret: 'yggio/generic/v2/any/unique/gatewaytopic/4321',
  health: "running",
  devices: {
    3: {
      lightSwitch: "on"
    }
  }
}

We are aware that this could be troublesome when integrating your gateway/cloud with Yggio. Possibly some kind of wildcard-solution, on our side, could be good here. Please contact us if this "flaw" is blocking your integration to Yggio! (yggio@sensative.com).

Yggio supported MQTT devices​

When connecting devices that already have an integration in Yggio, they are required to instead use the integrations root-topic. Below you can find a list of allowed (and integrated) devices.

  • Axis cameras | yggio/axis/v1/[your-sub-topic-here]

Axis Installation​

Start off by connecting your Axis-camera to a powersource and ethernet.

Identify what the IPv4-Address is for the connected camera. And go to https://[CAMERA-IP] with a computer connected to the same network.

root-password

Log in.

Go to

  1. Device view

  2. Maintenance axis-maintenance

Follow the instructions to update the firmware. Yggio supports up to 10.8.x

Axis subscription to Mqtt​

Go to our REST API Swagger

Authorize yourself at POST /auth/local

Take the token from the response and paste it in Authorize.

Scroll down to BasicCredentialsSets and make a POST /basic-credentials-sets.

Make sure to save the desired username, password and basicCredentialsSetId in a secure location!

Save the _id from the response and use it in the next step.

Scroll down to POST /reserved-mqtt-topics, paste the _id from previous step into basicCredentialsSetId and use yggio/generic/v2 followed by your own topics. Separated by /. See MQTT (data provider) for examples.

Axis camera local web interface​

  1. Device View

  2. MQTT

  3. staging.yggio.net as host

  4. MQTT over TCP

  5. 1883 as Port

  6. Username from BasicCredentialsSets

  7. Password from BasicCredentialsSets

  8. Save

  9. Connect axis-mqtt-connect

Axis Events​

  1. Device View

  2. Events

  3. MQTT Events

  4. Use default condition prefix -> OFF

  5. Paste in the topic you reserved in previous steps

  6. Add a condition and choose A3DPCCountingEvent

  7. Save. axis-mqtt-events

Axis Occupancy​

  1. Occupancy

  2. Estimate occupancy -> ON

  3. Allow Events -> ON axis-occupancy

Axis Counter​

You will see data coming from the device from here. counter

Configure device in Yggio​

After the above steps have been completed and the device has posted it's first message to the reserved MQTT topic, a device will be created in Yggio.

When the device is created, it's name will be MQTT - <topic that you chose>.

Set device model name to -> axis-p8815-2-3d-people-counter. device-monitor

Now go to Data and you will find your peopleCounter data.