Skip to content

Commit b97397d

Browse files
jason-foxjason-fox
committed
Expand static attributes explanation
1 parent 72e9501 commit b97397d

4 files changed

Lines changed: 90 additions & 47 deletions

File tree

‎README.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,11 +17,13 @@ directly or programmatically.
1717

1818
<h3>Data models</h3>
1919

20-
The tutorials defines a series of data-models to be used within the `@context`. More information about the classes and attributes
21-
used can be found in the following:
20+
The tutorials defines a series of data-models to be used within the `@context`. More information about the classes and
21+
attributes used can be found in the following:
2222

23-
- <img src="https://json-ld.org/favicon.ico" align="center" height="25"> [Tutorial-specific Data Models](https://ngsi-ld-tutorials.readthedocs.io/en/latest/datamodels.html)
24-
- <img src="https://json-ld.org/favicon.ico" align="center" height="25"> [Smart Data Models](https://smartdatamodels.org)
23+
- <img src="https://json-ld.org/favicon.ico" align="center" height="25">
24+
[Tutorial-specific Data Models](https://ngsi-ld-tutorials.readthedocs.io/en/latest/datamodels.html)
25+
- <img src="https://json-ld.org/favicon.ico" align="center" height="25">
26+
[Smart Data Models](https://smartdatamodels.org)
2527

2628
## Install
2729

‎docs/index.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -101,11 +101,13 @@ Scala code into a JAR file.
101101

102102
## Data models
103103

104-
The tutorials defines a series of data-models to be used within the `@context`. More information about the classes and attributes
105-
used can be found in the following:
104+
The tutorials defines a series of data-models to be used within the `@context`. More information about the classes and
105+
attributes used can be found in the following:
106106

107-
- <img src="https://json-ld.org/favicon.ico" align="center" height="30" width="30" style="border-right-style:solid; border-right-width:10px; border-color:transparent; background: transparent"> [Tutorial-specific Data Models](https://ngsi-ld-tutorials.readthedocs.io/en/latest/datamodels.html)
108-
- <img src="https://json-ld.org/favicon.ico" align="center" height="30" width="30" style="border-right-style:solid; border-right-width:10px; border-color:transparent; background: transparent"> [Smart Data Models](https://smartdatamodels.org)
107+
- <img src="https://json-ld.org/favicon.ico" align="center" height="30" width="30" style="border-right-style:solid; border-right-width:10px; border-color:transparent; background: transparent">
108+
[Tutorial-specific Data Models](https://ngsi-ld-tutorials.readthedocs.io/en/latest/datamodels.html)
109+
- <img src="https://json-ld.org/favicon.ico" align="center" height="30" width="30" style="border-right-style:solid; border-right-width:10px; border-color:transparent; background: transparent">
110+
[Smart Data Models](https://smartdatamodels.org)
109111

110112
## List of Tutorials
111113

@@ -124,7 +126,7 @@ Robots, IoT Sensors or other suppliers of context data such as social media. It
124126
from the context broker to alter the state of real-world objects themselves.
125127

126128
&nbsp; 201. [Introduction to IoT Sensors](iot-sensors.md)<br/> &nbsp; 202.
127-
[Provisioning the Ultralight IoT Agent](iot-agent.md)<br/> &nbsp; 203.
129+
[Provisioning the Ultralight IoT Agent](iot-agent.md)<br/> &nbsp; 203.
128130
[Provisioning the JSON IoT Agent](iot-agent-json.md)<br/>
129131

130132
<h3 style="box-shadow: 0px 4px 0px 0px #233c68;">Core Context Management: History Management</h3>

‎docs/iot-agent-json.md‎

Lines changed: 55 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
[![FIWARE IoT Agents](https://nexus.lab.fiware.org/repository/raw/public/badges/chapters/iot-agents.svg)](https://github.com/FIWARE/catalogue/blob/master/iot-agents/README.md)
22
[![JSON](https://img.shields.io/badge/Payload-JSON-f06f38.svg)](https://fiware-iotagent-json.readthedocs.io/en/latest/usermanual/index.html#user-programmers-manual)
33

4-
54
**Description:** This tutorial a wires up the dummy [JSON](https://json.org/)-based IoT devices using the
65
[IoT Agent for JSON](https://fiware-iotagent-json.readthedocs.io/en/latest/usermanual/index.html#user-programmers-manual)
76
devices so that measurements can be read and commands can be sent using
@@ -100,8 +99,8 @@ real world into the context data of the system.
10099
For example for a real-life **Soil Sensor** to send a humidity reading, the following interactions would occur:
101100

102101
1. A **Soil Sensor** makes a measurement and passes the result to the **IoT Agent**
103-
2. The **IoT Agent** receives this Northbound request, converts the result from JSON syntax and passes the result
104-
of the interaction into the context by making an NGSI-LD request to the **Context Broker**.
102+
2. The **IoT Agent** receives this Northbound request, converts the result from JSON syntax and passes the result of
103+
the interaction into the context by making an NGSI-LD request to the **Context Broker**.
105104
3. The **Context Broker** receives this Northbound request and updates the context with the result of the measurement.
106105

107106
![](https://fiware.github.io/tutorials.IoT-Agent-JSON/img/measurement-swimlane.png)
@@ -139,10 +138,10 @@ seen on the JSON device monitor web page found at: `http://localhost:3000/device
139138
This application builds on the components created in
140139
[previous tutorials](https://github.com/FIWARE/tutorials.Subscriptions/). It will make use of two FIWARE components - an
141140
NGSI-LD Context Broker such as [Orion](https://fiware-orion.readthedocs.io/en/latest/) and the
142-
[IoT Agent for JSON](https://fiware-iotagent-json.readthedocs.io/en/latest/). Usage of the Context Broker is
143-
sufficient for an application to qualify as _“Powered by FIWARE”_. Both the Orion Context Broker and the IoT Agent rely
144-
on open source [MongoDB](https://www.mongodb.com/) technology to keep persistence of the information they hold. We will
145-
also be using the dummy IoT devices created in the [previous tutorial](https://github.com/FIWARE/tutorials.IoT-Sensors/)
141+
[IoT Agent for JSON](https://fiware-iotagent-json.readthedocs.io/en/latest/). Usage of the Context Broker is sufficient
142+
for an application to qualify as _“Powered by FIWARE”_. Both the Orion Context Broker and the IoT Agent rely on open
143+
source [MongoDB](https://www.mongodb.com/) technology to keep persistence of the information they hold. We will also be
144+
using the dummy IoT devices created in the [previous tutorial](https://github.com/FIWARE/tutorials.IoT-Sensors/)
146145

147146
Therefore the overall architecture will consist of the following elements:
148147

@@ -152,8 +151,8 @@ Therefore the overall architecture will consist of the following elements:
152151
southbound requests using
153152
[NGSI-LD](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/rep/NGSI-LD/NGSI-LD/raw/master/spec/updated/generated/full_api.json)
154153
and convert them to
155-
[JSON](https://fiware-iotagent-json.readthedocs.io/en/latest/usermanual/index.html#user-programmers-manual)
156-
commands for the devices
154+
[JSON](https://fiware-iotagent-json.readthedocs.io/en/latest/usermanual/index.html#user-programmers-manual) commands
155+
for the devices
157156
- The underlying [MongoDB](https://www.mongodb.com/) database :
158157
- Used by the **Orion Context Broker** to hold context data information such as data entities, subscriptions and
159158
registrations
@@ -203,29 +202,29 @@ tutorial:
203202
The `tutorial` container is listening on two ports:
204203

205204
- Port `3000` is exposed so we can see the web page displaying the Dummy IoT devices.
206-
- Port `3001` is exposed purely for tutorial access - so that cUrl or Postman can make JSON commands without
207-
being part of the same network.
205+
- Port `3001` is exposed purely for tutorial access - so that cUrl or Postman can make JSON commands without being
206+
part of the same network.
208207

209208
The `tutorial` container is driven by environment variables as shown:
210209

211-
| Key | Value | Description |
212-
| ----------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
213-
| DEBUG | `tutorial:*` | Debug flag used for logging |
214-
| WEB_APP_PORT | `3000` | Port used by web-app which displays the dummy device data |
215-
| IOTA_HTTP_HOST | `iot-agent` | The hostname of the IoT Agent for JSON - see below |
216-
| IOTA_HTTP_PORT | `7896` | The port that the IoT Agent for JSON will be listening on. `7896` is a common default for JSON over HTTP |
217-
| DUMMY_DEVICES_PORT | `3001` | Port used by the dummy IoT devices to receive commands |
210+
| Key | Value | Description |
211+
| ----------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
212+
| DEBUG | `tutorial:*` | Debug flag used for logging |
213+
| WEB_APP_PORT | `3000` | Port used by web-app which displays the dummy device data |
214+
| IOTA_HTTP_HOST | `iot-agent` | The hostname of the IoT Agent for JSON - see below |
215+
| IOTA_HTTP_PORT | `7896` | The port that the IoT Agent for JSON will be listening on. `7896` is a common default for JSON over HTTP |
216+
| DUMMY_DEVICES_PORT | `3001` | Port used by the dummy IoT devices to receive commands |
218217
| DUMMY_DEVICES_API_KEY | `4jggokgpepnvsb2uv4s40d59ov` | Random security key used for JSON interactions - used to ensure the integrity of interactions between the devices and the IoT Agent |
219-
| DUMMY_DEVICES_TRANSPORT | `HTTP` | The transport protocol used by the dummy IoT devices |
220-
| DUMMY_DEVICES_PAYLOAD | `JSON` | The payload format used by the dummy IoT devices |
221-
| IOTA_JSON_LD_CONTEXT | `http://context:3000/data-models/ngsi-context.jsonld` | The location of the `@context` file used to define the device data models |
218+
| DUMMY_DEVICES_TRANSPORT | `HTTP` | The transport protocol used by the dummy IoT devices |
219+
| DUMMY_DEVICES_PAYLOAD | `JSON` | The payload format used by the dummy IoT devices |
220+
| IOTA_JSON_LD_CONTEXT | `http://context:3000/data-models/ngsi-context.jsonld` | The location of the `@context` file used to define the device data models |
222221

223222
The other `tutorial` container configuration values described in the YAML file are not used in this tutorial.
224223

225224
<h3>IoT Agent for JSON Configuration</h3>
226225

227-
The [IoT Agent for JSON](https://fiware-iotagent-json.readthedocs.io/en/latest/) can be instantiated within a
228-
Docker container. An official Docker image is available from [Docker Hub](https://hub.docker.com/r/fiware/iotagent-json/)
226+
The [IoT Agent for JSON](https://fiware-iotagent-json.readthedocs.io/en/latest/) can be instantiated within a Docker
227+
container. An official Docker image is available from [Docker Hub](https://hub.docker.com/r/fiware/iotagent-json/)
229228
tagged `fiware/iotagent-json`. The necessary configuration can be seen below:
230229

231230
```yaml
@@ -280,7 +279,7 @@ The `iot-agent` container is driven by environment variables as shown:
280279
| IOTA_LOG_LEVEL | `DEBUG` | The log level of the IoT Agent |
281280
| IOTA_TIMESTAMP | `true` | Whether to supply timestamp information with each measurement received from attached devices |
282281
| IOTA_CB_NGSI_VERSION | `LD` | Whether to supply use NGSI-LD when sending updates for active attributes |
283-
| IOTA_AUTOCAST | `true` | Ensure JSON number values are read as numbers not strings |
282+
| IOTA_AUTOCAST | `true` | Ensure JSON number values are read as numbers not strings |
284283
| IOTA_MONGO_HOST | `context-db` | The hostname of mongoDB - used for holding device information |
285284
| IOTA_MONGO_PORT | `27017` | The port mongoDB is listening on |
286285
| IOTA_MONGO_DB | `iotagentul` | The name of the database used in mongoDB |
@@ -301,10 +300,10 @@ technology which allows to different components isolated into their respective e
301300
- To install Docker on Linux follow the instructions [here](https://docs.docker.com/install/)
302301

303302
**Docker Compose** is a tool for defining and running multi-container Docker applications. A
304-
[YAML file](https://raw.githubusercontent.com/FIWARE/tutorials.IoT-Agent-JSON/NGSI-LD/docker-compose/orion-ld.yml) is used
305-
configure the required services for the application. This means all container services can be brought up in a single
306-
command. Docker Compose is installed by default as part of Docker for Windows and Docker for Mac, however Linux users
307-
will need to follow the instructions found [here](https://docs.docker.com/compose/install/)
303+
[YAML file](https://raw.githubusercontent.com/FIWARE/tutorials.IoT-Agent-JSON/NGSI-LD/docker-compose/orion-ld.yml) is
304+
used configure the required services for the application. This means all container services can be brought up in a
305+
single command. Docker Compose is installed by default as part of Docker for Windows and Docker for Mac, however Linux
306+
users will need to follow the instructions found [here](https://docs.docker.com/compose/install/)
308307

309308
You can check your current **Docker** and **Docker Compose** versions using the following commands:
310309

@@ -510,8 +509,7 @@ sending GET or POST requests to:
510509
http://iot-agent:7896/iot/d?i=<device_id>&k=4jggokgpepnvsb2uv4s40d59ov
511510
```
512511

513-
Which should be familiar syntax from the
514-
[previous tutorial](iot-sensors.md).
512+
Which should be familiar syntax from the [previous tutorial](iot-sensors.md).
515513

516514
The service group provisioning can also be used to define `attributes` mappings and common `static_attributes`. The
517515
`attributes` mappings define common aliases for anonymous incoming devices. For example the key `gps` can be defined to
@@ -584,7 +582,28 @@ curl -L -X POST 'http://localhost:4041/iot/devices' \
584582
In the request we are associating the device `temperature001` with the URN `urn:ngsi-ld:Device:temperature001` and
585583
mapping the device reading `t` with the context attribute `temperature` (which is defined as **Property** with
586584
appropriate meta-data). A `controlledAsset` **Relationship** is also defined as a `static_attribute`, placing the device
587-
within the **Building** `urn:ngsi-ld:Building:barn001`
585+
within the **Building** `urn:ngsi-ld:Building:barn001`.
586+
587+
> Static attributes are useful as additional data on an entity to enable querying using the `q` parameter. For example
588+
> the Smart Data Models [Device](https://github.com/smart-data-models/dataModel.Device/blob/master/Device/doc/spec.md)
589+
> model defines attributes such as `category` or `controlledProperty` which enable queries to be made like:
590+
>
591+
> - _Which **Actuators** currently have a low `batteryLevel`?_
592+
>
593+
> `/ngsi-ld/v1/entities?q=category=="actuator";batteryLevel<0.1`
594+
>
595+
> - _Which **Devices** measuring `fillingLevel` were installed before January 2020?_
596+
>
597+
> `/ngsi-ld/v1/entities?q=controlledProperty=="fillingLevel";dateInstalled<"2020-01-25T00:00:00.000Z"`
598+
>
599+
> Obviously static data can be extended as necessary and can also include additional data such as a unique `name` or
600+
> `serialNumber` for each device should the entity ID be too inflexible for queries.
601+
>
602+
> `/ngsi-ld/v1/entities?q=serialNumber=="XS403001-002"`
603+
>
604+
> Additionally devices with a fixed `location` static attribute can also be queried using the Geofencing parameters.
605+
>
606+
> `/ngsi-ld/v1/entities?georel=near;maxDistance:1500&geometry=point&coords=52.5162,13.3777`
588607

589608
You can simulate a dummy IoT device measurement coming from the **Temperature Sensor** device `temperature001`, by
590609
making the following request
@@ -699,8 +718,8 @@ curl -L -X GET 'http://localhost:1026/ngsi-ld/v1/entities/?type=Device' \
699718
```
700719

701720
As you can see, the Entity type and `static_attributes` from the service group have been copied over to the entity in
702-
the context broker, however since the measure `{"c": 1}` does not have a mapping, the name of the Property has been copied
703-
directly from the received measure.
721+
the context broker, however since the measure `{"c": 1}` does not have a mapping, the name of the Property has been
722+
copied directly from the received measure.
704723

705724
### Provisioning an Actuator
706725

@@ -932,8 +951,7 @@ available. In other words the IoT Agent registered itself as a
932951

933952
Once the commands have been registered it will be possible to turn on the **water**, open and close the **Smart Door**
934953
and switch the **Irrigation System** on and off by sending requests to the Orion Context Broker, rather than sending
935-
JSON requests directly the IoT devices as we did in the
936-
[previous tutorial](iot-sensors.md)
954+
JSON requests directly the IoT devices as we did in the [previous tutorial](iot-sensors.md)
937955

938956
### Activating the Irrigation System
939957

@@ -1184,8 +1202,8 @@ curl -iX PUT \
11841202

11851203
This example removes a provisioned service group by making a DELETE request to the `/iot/services/` endpoint.
11861204

1187-
It means that requests to `http://iot-agent:7896/iot/json?i=<device_id>&k=4jggokgpepnvsb2uv4s40d59ov` (where the IoT Agent
1188-
is listening for **Northbound** communications) should no longer be processed by the IoT Agent. The `apiKey` and
1205+
It means that requests to `http://iot-agent:7896/iot/json?i=<device_id>&k=4jggokgpepnvsb2uv4s40d59ov` (where the IoT
1206+
Agent is listening for **Northbound** communications) should no longer be processed by the IoT Agent. The `apiKey` and
11891207
`resource` parameters must be supplied in order to identify the service group to be deleted.
11901208

11911209
#### 21 Request:

0 commit comments

Comments
 (0)