Let Things5 read, write and delete the recipes stored on the device.
Things5 platform syncs all recipes available on the device once. So that when a user on things5 needs to get a recipe can do so even if the device is offline.
To do so things5 sends both a Read recipes request and a List recipes request.
If your hardware has very limited hardware resources and cannot send all recipes at once subscribe to list recipes request and ignore read recipes request. Things5 will send a separate Read recipe request for each recipe id provided.
Choose this method also if there are a lot of recipes since the mqtt payload cannot be over 128KB
Otherwise subscribe to Read recipes request and send all device recipes as a response.
When the user creates/edits a recipe things5 sends a write recipe request This request is expected to write the edited/new recipe on the device without touching the other recipes on the device.
NOTE: to support legacy apis things5 also sends a write recipes request when creating/editing a recipe. Please ignore it.
There are 11 topics:
Subscribe
-
[Sub] Read recipes request: listen for read recipe requests
-
[Sub] Read recipe request: listen for read recipe request
-
[Sub] List recipes request: listen for list recipe requests
-
[Sub] Write recipe request: listen for write recipe requests
-
[Sub] Delete recipe request : listen for delete recipe requests
Publish
- [Pub] Read recipes response: publish requested device recipes
- [Pub] Read recipe response: publish requested device recipe
- [Pub] List recipes response: publish requested device recipes ids
- [Pub] Write recipe response: publish written device recipe
- [Pub] Delete recipe response: publish delete machine recipe success/errors
- [Pub] Recipes updated manually: publish on this topic to notify that recipes have been manually updated on a machine
Recipe structure
| name | type | description | example |
|---|---|---|---|
| id | string | recipe id. Can be any unique string. If present update the recipe, otherwise create a new recipe | "83412jnjasdlfnha1234" |
| can_be_edited | boolean | ||
| can_be_deleted | boolean | ||
| name | string | recipe name | "Pollo con patate" |
| description | string | recipe description | |
| index | integer | the recipe index starting from 0. Can be used by device to order the recipes. | |
| phases | objects array | an array of objects with a values property that lists each variable name, value and type. Values type can be integer, float, string, boolean. Dosages is optional. dosages type can be integer or float | [ { "values": [ { "name": "tim", "value": "5", "type": "integer" }, { "name": "wrk", "value": "PREPARATION", "type": "string" }, { "name": "s1", "value": "0", "type": "integer" }, { "name": "s2", "value": "0", "type": "integer" }, { "name": "tmp", "value": "0", "type": "integer" } ], "dosages": [ { "name": "2", "unit": "g", "quantity": "10000", "type": "integer", "metadata": [{ "name": "wait", "value": "0", "type": "integer" }] } ] }, { "values": [ { "name": "tim", "value": "480", "type": "integer" }, { "name": "wrk", "value": "V1", "type": "string" }, { "name": "s1", "value": "0", "type": "integer" }, { "name": "s2", "value": "0", "type": "integer" }, { "name": "tmp", "value": "0", "type": "integer" } ], "dosages": [] } ] |
| metadata | object | Custom attributes. Type can be integer, float, string, boolean | [ { "name": "max_t", "value": "0", "type": "integer" }, { "name": "weight", "value": "16830", "type": "integer" }, { "name": "pieces", "value": "48", "type": "integer" } ] |
| Topic | Direction |
|---|---|
things5-production/v1/devices/{device_id}/cmd/read_recipes_req | Things5 → device |
things5-production/v1/devices/{device_id}/cmd/read_recipes_res | Device → Things5 |
things5-production/v1/devices/{device_id}/cmd/list_recipes_req | Things5 → device |
things5-production/v1/devices/{device_id}/cmd/list_recipes_res | Device → Things5 |
things5-production/v1/devices/{device_id}/cmd/read_recipe_req | Things5 → device |
things5-production/v1/devices/{device_id}/cmd/read_recipe_res | Device → Things5 |
things5-production/v1/devices/{device_id}/cmd/write_recipe_req | Things5 → device |
things5-production/v1/devices/{device_id}/cmd/write_recipe_res | Device → Things5 |
things5-production/v1/devices/{device_id}/cmd/delete_recipe_req | Things5 → device |
things5-production/v1/devices/{device_id}/cmd/delete_recipe_res | Device → Things5 |
things5-production/v1/devices/{device_id}/event/recipes_updated_manually | Device → Things5 |
Things5 → device: cmd/read_recipes_req
cmd/read_recipes_reqSubscribe to this topic to receive read recipes requests.
Publish on write recipes response to send the requested recipes.
things5-production/v1/devices/<device-id>/cmd/read_recipes_req
Payload
{
"request_id": "UUID",
"metadata": {
"is_menu": "true",
"parent_id": "123"
}
}
Payload Parameters
| type | description | example |
|---|---|---|
| request_id | the request id to be sent back by the device when sending the response |
Expected response
Response has to be sent into the
things5-production/v1/devices/<device-id>/cmd/read_recipes_restopic
Device → Things5: cmd/read_recipes_res
cmd/read_recipes_resPublish on this topic to send a response for a previous read recipes request.
Response is expected to contain all device recipes.
things5-production/v1/devices/<device-id>/cmd/read_recipes_res
Payload
{
"request_id": "UUID sent in the request",
"recipes": [
{
"id": "uniqueid",
"can_be_edited": true,
"can_be_deleted": false,
"name": "Pollo con patate al cuore",
"description": "Recipe description",
"index": 0,
"phases": [
{
"dosages": [
{
"name": "yeast",
"quantity": "5.5",
"unit": "g",
"type": "float",
"metadata": [
{
"name": "type",
"value": "1",
"type": "integer"
},
{
"name": "temperature",
"value": "20",
"type": "integer"
}
]
}
],
"values": [
{
"name": "evaporator_fan_speed",
"value": "4",
"type": "integer"
},
{
"name": "core_temperature",
"value": "-5",
"type": "integer"
},
{
"name": "cell_temperature",
"value": "-20",
"type": "integer"
}
]
},
{
"values": [
{
"name": "evaporator_fan_speed",
"value": "2",
"type": "integer"
},
{
"name": "core_temperature",
"value": "-5",
"type": "integer"
},
{
"name": "cell_temperature",
"value": "-20",
"type": "integer"
}
]
},
{
"values": [
{
"name": "evaporator_fan_speed",
"value": "1",
"type": "integer"
},
{
"name": "core_temperature",
"value": "-5",
"type": "integer"
},
{
"name": "cell_temperature",
"value": "-20",
"type": "integer"
}
]
},
{
"values": [
{
"name": "evaporator_fan_speed",
"value": "0",
"type": "integer"
},
{
"name": "cell_temperature",
"value": "-10",
"type": "integer"
}
]
}
],
"metadata": [
{
"name": "image_path",
"value": "../images/fish.jpg",
"type": "string"
},
{
"name": "index_in_list",
"value": "6",
"type": "integer"
}
]
}
]
}
Things5 → device: cmd/list_recipes_req
cmd/list_recipes_reqThis topic is a lightweight alternative of read recipes request. You can find more info in the introduction section.
Subscribe to this topic to receive list recipes requests.
Publish on list recipes response to send the list of recipes ids.
things5-production/v1/devices/<device-id>/cmd/list_recipes_req
Payload
{
"request_id": "UUID"
}
Payload Parameters
| type | description | example |
|---|---|---|
| request-id | the request id to be sent back by the device when sending the response |
Expected response
: Response has to be sent into the
things5-production/v1/devices/<device-id>/cmd/list_recipes_restopic
Device → Things5: cmd/list_recipes_res
cmd/list_recipes_resPublish on this topic to send a response for a previous read recipes request.
Response is expected to contain all device recipes.
things5-production/v1/devices/<device-id>/cmd/list_recipes_res
Payload
{
"request_id":"UUID sent in the request",
"recipes_ids": ["1","2","3"],
"recipes_names": ["chicken", "fish", "cookies"]
}
Things5 → device: cmd/read_recipe_req
cmd/read_recipe_reqSubscribe to this topic to receive read recipes requests.
Publish on read recipe response to send the requested recipes.
things5-production/v1/devices/<device-id>/cmd/read_recipe_req
Payload
{
"request_id": "UUID",
"recipe_id": "123"
}
Payload Parameters
| type | description | example |
|---|---|---|
| request_id | the request id to be sent back by the device when sending the response | |
| recipe_id | the id of the requested recipe |
Expected response
: Response has to be sent into the
things5-production/v1/devices/<device-id>/cmd/read_recipe_restopic
Device → Things5: cmd/read_recipe_res
cmd/read_recipe_resPublish on this topic to send a response for a previous read recipes request.
Response is expected to contain all device recipes.
things5-production/v1/devices/<device-id>/cmd/read_recipe_res
Payload
{
"request_id": "UUID sent in the request",
"recipe": {
"id": "uniqueid",
"can_be_edited": true,
"can_be_deleted": false,
"name": "Pollo con patate al cuore",
"description": "Recipe description",
"index": 1,
"phases": [
{
"dosages":
[
{
"name": "yeast",
"quantity": "5.5",
"type": "float",
"unit": "g",
"metadata" : [{
"name": "type",
"value": "1",
"type": "integer"
}, {
"name": "temperature",
"value": "20",
"type": "integer"
}]
}
],
"values": [
{
"name": "evaporator_fan_speed",
"value": "4",
"type": "integer"
},
{
"name": "core_temperature",
"value": "-5",
"type": "integer"
},
{
"name": "cell_temperature",
"value": "-20",
"type": "integer"
}
]
},
{
"values": [
{
"name": "evaporator_fan_speed",
"value": "2",
"type": "integer"
},
{
"name": "core_temperature",
"value": "-5",
"type": "integer"
},
{
"name": "cell_temperature",
"value": "-20",
"type": "integer"
}
]
},
{
"values": [
{
"name": "evaporator_fan_speed",
"value": "1",
"type": "integer"
},
{
"name": "core_temperature",
"value": "-5",
"type": "integer"
},
{
"name": "cell_temperature",
"value": "-20",
"type": "integer"
}
]
},
{
"values": [
{
"name": "evaporator_fan_speed",
"value": "0",
"type": "integer"
},
{
"name": "cell_temperature",
"value": "-10",
"type": "integer"
}
]
}
],
"metadata": [
{
"name": "image_path",
"value": "../images/fish.jpg",
"type": "string"
},
{
"name": "index_in_list",
"value": "6",
"type": "integer"
}
]
}
}
Things5 → device: cmd/write_recipe_req
cmd/write_recipe_reqSubscribe to this topic to accept write recipe requests.
Write a single recipe without changing all the other recipes on the device
things5-production/v1/devices/<device-id>/cmd/write_recipe_req
Payload
{
"request_id": "UUID sent in the request",
"recipe": {
"id": "uniqueid",
"name": "Pollo con patate al cuore",
"description": "Recipe description",
"type": "core",
"index": 1,
"phases": [
{
"values": [
{
"name": "evaporator_fan_speed",
"value": "4",
"type": "integer"
},
{
"name": "core_temperature",
"value": "-5",
"type": "integer"
},
{
"name": "cell_temperature",
"value": "-20",
"type": "integer"
}
]
},
{
"values": [
{
"name": "evaporator_fan_speed",
"value": "2",
"type": "integer"
},
{
"name": "core_temperature",
"value": "-5",
"type": "integer"
},
{
"name": "cell_temperature",
"value": "-20",
"type": "integer"
}
]
},
{
"values": [
{
"name": "evaporator_fan_speed",
"value": "1",
"type": "integer"
},
{
"name": "core_temperature",
"value": "-5",
"type": "integer"
},
{
"name": "cell_temperature",
"value": "-20",
"type": "integer"
}
]
},
{
"values": [
{
"name": "evaporator_fan_speed",
"value": "0",
"type": "integer"
},
{
"name": "cell_temperature",
"value": "-10",
"type": "integer"
}
]
}
],
"metadata": [
{ "name": "datetime", "type": "integer", "value": "1715681973" },
{ "name": "origin", "type": "integer", "value": "0" }
]
}
}
Payload Parameters
| name | description | example |
|---|---|---|
| request_id | the request id to be sent back by the device when sending the response | |
| recipes | list of recipes to write |
Recipe type
| name | required |
|---|---|
| id | false |
| name | true |
| description | false |
| type | false |
| phases | true |
| metadata | false |
Response has to be sent into the write recipe response:
Device → Things5: cmd/write_recipe_res
cmd/write_recipe_resPublish on this topic to send a response for a previous write recipee request.
Response must contain the written recipe.
things5-production/v1/devices/<device-id>/cmd/write_recipe_res
Payload
{
"request_id": "UUID sent in the request",
"errors": ["errors if any"],
"recipe": {
"id": "uniqueid",
"can_be_edited": true,
"can_be_deleted": false,
"name": "Pollo con patate al cuore",
"description": "Recipe description",
"index": 1,
"phases": [
{
"dosages":
[
{
"name": "yeast",
"quantity": "5.5",
"type": "float",
"unit": "g",
"metadata" : [{
"name": "type",
"value": "1",
"type": "integer"
}, {
"name": "temperature",
"value": "20",
"type": "integer"
}]
}
],
"values": [
{
"name": "evaporator_fan_speed",
"value": "4",
"type": "integer"
},
{
"name": "core_temperature",
"value": "-5",
"type": "integer"
},
{
"name": "cell_temperature",
"value": "-20",
"type": "integer"
}
]
},
{
"values": [
{
"name": "evaporator_fan_speed",
"value": "2",
"type": "integer"
},
{
"name": "core_temperature",
"value": "-5",
"type": "integer"
},
{
"name": "cell_temperature",
"value": "-20",
"type": "integer"
}
]
},
{
"values": [
{
"name": "evaporator_fan_speed",
"value": "1",
"type": "integer"
},
{
"name": "core_temperature",
"value": "-5",
"type": "integer"
},
{
"name": "cell_temperature",
"value": "-20",
"type": "integer"
}
]
},
{
"values": [
{
"name": "evaporator_fan_speed",
"value": "0",
"type": "integer"
},
{
"name": "cell_temperature",
"value": "-10",
"type": "integer"
}
]
}
],
"metadata": [
{
"name": "image_path",
"value": "../images/fish.jpg",
"type": "string"
},
{
"name": "index_in_list",
"value": "6",
"type": "integer"
}
]
}
}
Things5 → device: cmd/delete_recipe_req
cmd/delete_recipe_reqSubscribe to this topic to accept delete recipe requests.
Delete a single recipe.
things5-production/v1/devices/<device-id>/cmd/delete_recipe_req
Payload
{
"request_id": "UUID sent in the request",
"recipe_id": "recipe unique id"
}
Payload Parameters
| name | description | example | required |
|---|---|---|---|
| request_id | the request id to be sent back by the device when sending the response | ||
| recipe_id | string. the recipe unique id | true |
: Response has to be sent into the delete recipe response
Device → Things5: cmd/delete_recipe_res
cmd/delete_recipe_resPublish on this topic to send a response for a previous delete recipe request.
things5-production/v1/devices/<device-id>/cmd/delete_recipe_res
Payload
{
"request_id": "UUID sent in the request",
"recipe_id": "id of the recipe",
"errors": ["errors if any"]
}
Device → Things5: event/recipes_updated_manually
event/recipes_updated_manuallyPublish on this topic when recipes are updated manually on a device.
When recipes are changed directly on a machine publish an empty message on this topic to notify Things5 of the changes.
things5-production/v1/devices/<device-id>/event/recipes_updated_manually
Legacy messages
To support older devices Things5 can also send cmd/write_recipes_req (replace all recipes). New devices can ignore it and answer cmd/write_recipe_req only.