Topic/Thing

The topic handles all the activities regarding the Thing description (properties, actions and events). However, it is important to differ between two different types of topics: status and set topics. Each one of these will behave differently within the Thing description.

Status Topics

Status is only used to subscribe to a certain Thing. You can subscribe to the Thing's properties, actions, or events by using an MQTT subscribe request to the following topics:

Properties: status/<account-id>/collections/<collection-id>/things/<thing-UID>/properties/<property-id>
Actions: status/<account-id>/collections/<collection-id>/things/<thing-UID>/actions/<action-id>
Events: status/<account-id>/collections/<collection-id>/things/<thing-UID>/events/<event-id>

Example of a MQTT subscribe to receive a requested action from a given Thing:

SUBSCRIBE status/myspace/collections/my-collection/things/01FDSA7KS76MNR32J8W0RAWEFX/actions/Volumechange

Example of the message received when an action is requested:

{
  "Volumechange": {
    "input": {
      "level": 70,
      "duration": 2500
    },
    "href": "/things/001/actions/Volumechange/123e4567-e89b-12d3-a456-426655",
    "timeRequested": "2017-01-25T15:01:35+00:00",
    "status": "pending"
  }
}

To receive all actions of one particular Thing, subscribe to the following MQTT topic:

SUBSCRIBE status/myspace/collections/my-collection/things/01FDSA7KS76MNR32J8W0RAWEFX/actions/+

The return message gives you the action object of all the actions you requested to your Thing:

Message 1:
      {
         "Volumechange": {
            "input": {
                 "level": 70,
                 "duration": 2500
             },
         "href": "/things/001/actions/Volumechange/18",
         "timeRequested": "2017-01-25T15:01:35+00:00",
         "status": "pending"
       }
    }
Message 2:
    {
    "reboot": {
      "href": "/things/Sound/actions/reboot/12",
      "timeRequested": "2017-01-24T13:13:33+00:00",
      "timeCompleted": "2017-01-24T13:15:01+00:00",
      "status": "completed"
    }
    }

Set Topics

This topic handles the creation and updates of the Thing properties, actions and events. Using MQTT requests you can create or update the value of the elements that you defined in the Thing description. More precisely you can create or update a property, action or event by publishing to the following topics:

Properties: set/<account-id>/collections/<collection-id>/things/<thing-UID>/properties/<property-id>
Actions: set/<account-id>/collections/<collection-id>/things/<thing-UID>/actions/<action-id>
Events: set/<account-id>/collections/<collection-id>/things/<thing-UID>/events/<event-id>

Publishing to MQTT, in this case, triggers the same action as an HTTP PUT request to update or an HTTP POST to create. To publish on actions to add a new Thing action to the actions queue, follow this example:

PUBLISH set/myspace/collections/my-collection/things/01FDSA7KS76MNR32J8W0RAWEFX/actions/Volumechange
 
{
    "Volumechange": {
        "input": {
        "level": 70,
        "duration": 2500
        }
    }
}

If you are subscribed to the status topic selected above, you will receive the following message:

{
    "Volumechange": {
        "href": "/things/001/actions/Volumechange/12",
        "input": {
            "duration": 2500,
            "level": 70
        },
        "status": "pending",
        "timeRequested": "2020-05-29T11:09:06+0000"
    }
}

Update an action using MQTT publishing with the following example:

set/myspace/collections/my-collection/things/01FDSA7KS76MNR32J8W0RAWEFX/actions/Volumechange/12

Message:

{
	"Volumechange":{
	  "status":"Completed"
  }
}

If you are subscribed to the status topic you will receive the following message:

{
    "Volumechange": {
        "href": "/things/001/actions/Volumechange/12",
        "input": {
            "duration": 2500,
            "level": 70
        },
        "status": "Completed",
        "timeCompleted": "2020-05-29T11:14:41+0000",
        "timeRequested": "2020-05-29T11:09:06+0000"
    }
}