Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add command entity creation documentation #1551

Merged
merged 26 commits into from
Jul 31, 2024
Merged
Changes from 5 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions doc/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
- [Config groups](#config-groups)
- [Devices](#devices)
- [Entity attributes](#entity-attributes)
- [Device autoprovision and entity creation](#device-autoprovision-and-entity-creation)
- [Multientity support)](#multientity-support)
- [Metadata support](#metadata-support)
- [NGSI LD data and metadata considerations](#ngsi-ld-data-and-metadata-considerations)
Expand All @@ -29,6 +30,7 @@
- [Measurement transformation execution](#measurement-transformation-execution)
- [Measurement transformation order](#measurement-transformation-order)
- [Multientity measurement transformation support (`object_id`)](#multientity-measurement-transformation-support-object_id)
- [Commands execution](#commands-execution)
- [Timestamp Processing](#timestamp-processing)
- [Overriding global Context Broker host](#overriding-global-context-broker-host)
- [Multitenancy, FIWARE Service and FIWARE ServicePath](#multitenancy-fiware-service-and-fiware-servicepath)
Expand Down Expand Up @@ -215,6 +217,12 @@ Note that, when information coming from devices, this means measures, are not de
device, the IoT agent will store that information into the destination entity using the same attribute name than the
measure name, unless `explicitAttrs` is defined. Measures `id` or `type` names are invalid, and will be ignored.

## Device autoprovision and entity creation
mapedraza marked this conversation as resolved.
Show resolved Hide resolved

For those agents that uses IoTA Node LIB version 3.4.0 or higher, you should consider that the entity is not created
automaticaly when a device is created. This means that al entities into the context broker are created when data
arrives from a device, either if the device is created or autoprovisioned.
mapedraza marked this conversation as resolved.
Show resolved Hide resolved
mapedraza marked this conversation as resolved.
Show resolved Hide resolved

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we should a paragraph explaining what to do if you need the entity in advance? Something like this:

If for any reason you need the entity at CB before the first measure of the corresponding device arrives to the IOTAgent, you can create it in advance using the CB NGSIv2 API.

Please, adapt/improve the text as needed.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added in 557f75a

## Multientity support

The IOTA is able to persists measures coming from a single device to more than one entity, declaring the target entities
Expand Down Expand Up @@ -955,6 +963,33 @@ The IOTA processes the entity attributes looking for a `TimeInstant` attribute.
adds a `TimeInstant` attribute as metadata for every other attribute in the same request. With NGSI-LD, the Standard
`observedAt` property-of-a-property is used instead.

## Commands execution
mapedraza marked this conversation as resolved.
Show resolved Hide resolved

The way to act upon devices is through the usage of commnamds. Commands are specific set attributes that allows to
send information to the device. They are defined in the device provision.

In order to trigger the command, it is required to update the command attribute in the Orion Context Broker. You
can use a PUT request as the following one:

```bash
curl -L -X PUT 'http://localhost:1026/v2/entities/<ENTITY_ID>/attrs/<CMD_NAME>?type=<ENTITY_TYPE>' \
-H 'Content-Type: application/json' \
-d '{
"type" : "command",
"value" : "commandValue"
}'
```

**Note**: It is mandatory to add the `type` URL parameter with the entity type to the request, otherwise, you could
get the following error message:

```json
{
"error": "NotFound",
"description": "The requested entity has not been found. Check type and id"
}
```

mapedraza marked this conversation as resolved.
Show resolved Hide resolved
## Overriding global Context Broker host
fgalan marked this conversation as resolved.
Show resolved Hide resolved

**cbHost**: Context Broker host URL. This option can be used to override the global CB configuration for specific types
Expand Down
Loading