Skip to content

Commit 513733c

Browse files
jason-foxjason-fox
committed
Annotate environment variables.
1 parent a6ba15f commit 513733c

File tree

2 files changed

+116
-98
lines changed

2 files changed

+116
-98
lines changed

‎app/README.md‎

Lines changed: 51 additions & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -1,114 +1,84 @@
1-
This is a simple Node.js express application which offers an NGSI proxy interface to four context providers.
1+
# FIWARE NGSI-LD Step-by-Step Tutorials Web App
22

3-
# NGSI-LD `/ngsi-ld/v1/entities/` Endpoints
3+
[![Documentation](https://nexus.lab.fiware.org/repository/raw/public/badges/chapters/documentation.svg)](https://fiware-tutorials.rtfd.io)
4+
[![Docker](https://img.shields.io/docker/pulls/fiware/tutorials.ngsi-ld.svg)](https://hub.docker.com/r/fiware/tutorials.ngsi-ld/)
5+
[![Support badge](https://img.shields.io/badge/tag-fiware-orange.svg?logo=stackoverflow)](https://stackoverflow.com/questions/tagged/fiware)
6+
[![NGSI LD](https://img.shields.io/badge/NGSI-LD-d6604d.svg)](https://cim.etsi.org/NGSI-LD/official/front-page.html)
7+
[![JSON LD](https://img.shields.io/badge/JSON--LD-1.1-f06f38.svg)](https://w3c.github.io/json-ld-syntax/)
48

5-
Supported NGSI-LD context provider endpoints
9+
This is a Node.js Express application that serves as the main web interface for the FIWARE NGSI-LD Step-by-Step
10+
tutorials. It acts as a multi-purpose component, functioning as a Context Provider, a User Interface, and a secure proxy
11+
to other FIWARE components.
612

7-
- `/random/temperature/ngsi-ld/v1/entities/`
8-
- `/random/relativeHumidity/ngsi-ld/v1/entities/`
9-
- `/random/tweets/ngsi-ld/v1/entities/`
10-
- `/random/weatherConditions/ngsi-ld/v1/entities/`
11-
- `/static/temperature/ngsi-ld/v1/entities/`
12-
- `/static/relativeHumidity/ngsi-ld/v1/entities/`
13-
- `/static/tweets/ngsi-ld/v1/entities/`
14-
- `/static/weatherConditions/ngsi-ld/v1/entities/`
15-
- `/catfacts/tweets/ngsi-ld/v1/entities/`
16-
- `/twitter/tweets/ngsi-ld/v1/entities/`
17-
- `/weather/temperature/ngsi-ld/v1/entities/`
18-
- `/weather/relativeHumidity/ngsi-ld/v1/entities/`
19-
- `/weather/weatherConditions/ngsi-ld/v1/entities/`
13+
## Features
2014

21-
The following dynamic NGSI-LD endpoints are supported
15+
* **Context Provider**: Exposes multiple NGSI-LD endpoints to provide context data (static, random, or proxied from external APIs like Twitter and OpenWeatherMap).
16+
* **Web Interface**: Renders web pages using Pug templates to visualize data and interact with the system.
17+
* **Data Persistence**: Connects to MongoDB for storing session data and application state.
18+
* **History Visualization**: Fetches and aggregates historical data for visualization.
19+
* **NGSI-LD Proxy**: Interactions with a Context Broker (e.g., Orion-LD, Scorpio Stellio).
20+
* **Device Control**: Provides an interface to send commands to dummy IoT devices via the Context Broker.
2221

23-
- `/random/<type>/<mapping>/ngsi-ld/v1/entities/:id`. returns random data values of `"type": "<type>"` - e.g.
24-
`/random/text/quote/ngsi-ld/v1/entities/:id` will return random lorem ipsum
22+
## Endpoints
2523

26-
- `/static/<type>/<mapping>/ngsi-ld/v1/entities/:id` returns static data values of `"type": "<type>"` - e.g.
27-
`/static/text/quote/ngsi-ld/v1/entities/:id` will return "I never could get the hang of thursdays"
24+
### NGSI-LD Context Provider Endpoints
2825

29-
- `/twitter/<type>/<mapping><queryString>/<attr>/ngsi-ld/v1/entities/:id` Work in progress
26+
The application provides context data under `/ngsi-ld/v1/entities/`:
3027

31-
- `/weather/<type>/<mapping>/<queryString>/<attr>/ngsi-ld/v1/entities/:id` Retrieves the Weather data for the
32-
`queryString` location and maps the data from the given `attr` to the entity response.
28+
- **Random Data**: `/random/<type>/...`
29+
- **Static Data**: `/static/<type>/...`
30+
- **Twitter Data**: `/catfacts/...`, `/twitter/...`
31+
- **Weather Data**: `/weather/...`
3332

34-
For Example `/weather/number/berlin%2cde/wind_speed/ngsi-ld/v1/entities/:id` will read the `wind_speed` value from
35-
Berlin. and `/weather/number/cairo%2ceg/temp/ngsi-ld/v1/entities/:id` will read the `temp` value from Cairo.
33+
### Health Checks
3634

37-
## Mappings
35+
- `/health`: General application health check.
36+
- `/random/health`, `/static/health`: Check availability of random/static context providers.
37+
- `/twitter/health`: Check connectivity to Twitter API.
38+
- `/weather/health`: Check connectivity to OpenWeatherMap API.
3839

39-
NGSI attribute names should follow Data Model Guidelines (e.g. `camelCasing`) Data returned from third-party APIs will
40-
not enforce the same guidelines. It is therefore necessary to invoke a mapping to be able to know which values to
41-
retieve.
40+
## Environment Variables
4241

43-
The mapping path element is assumes that mappings are defined in the path as follows:
42+
The application is configured using the following environment variables:
4443

45-
- `temperature`
46-
- `temperature` NGSI attribute maps to `temperature` attribute on the API data
47-
- `temperature:temp`
48-
- `temperature` NGSI attribute maps to `temp` attribute on the API data
49-
- `temperature:temp,windSpeed:wind_speed`
50-
- `temperature` NGSI attribute maps to `temp` attribute on the API data
51-
- `windSpeed` NGSI attribute maps to `wind_speed` attribute on the API data
44+
### Core Configuration
5245

53-
For the full guidelines see the
54-
[FIWARE Data Models](https://fiware-datamodels.readthedocs.io/en/latest/guidelines/index.html)
46+
- `WEB_APP_PORT` - Port the application listens on. Default: `3000`.
47+
- `NODE_ENV` - Environment mode (e.g., `production`, `development`).
48+
- `DEBUG` - Debug logging namespace. Recommended: `tutorial:*`.
49+
- `SESSION_SECRET` - Secret used for signing session cookies.
50+
- `SESSION_OFF` - If set to `true`, disables session management. Default: `false`.
5551

56-
## Health Check Endpoints
52+
### Database Connectivity
5753

58-
The following health check endpoints are supported:
54+
- `MONGO_URL` - Connection string for MongoDB. Default: `mongodb://localhost:27017`.
5955

60-
- `/random/health` A non-error response shows that an NGSI proxy is available on the network and returning values.
61-
Each Request will return some random dummy data.
56+
### FIWARE Component Connectivity
6257

63-
- `/static/health` A non-error response shows that an NGSI proxy is available on the network and returning values.
64-
Each Request will return the same data.
58+
- `CONTEXT_BROKER` - URL of the Context Broker. Default: `http://localhost:1026/ngsi-ld/v1`.
59+
- `DEVICE_BROKER` - URL for device commands, usually same as Context Broker. Default: same as `CONTEXT_BROKER`.
60+
- `NGSI_LD_TENANT` - Tenant for NGSI-LD requests. Default: `openiot`.
61+
- `IOTA_JSON_LD_CONTEXT` - JSON-LD Context URL for device commands. Default: `http://localhost:3000/data-models/ngsi-context.jsonld`.
6562

66-
- `/catfacts/health` A non-error response shows that an NGSI proxy is available on the network and returning values.
67-
Each Request will return the same data.
63+
### IoT Device Connectivity
6864

69-
- `/twitter/health` A non-error response shows that an NGSI proxy for the Twitter API is available on the network and
70-
returning values.
65+
Variables to configure the connection to the Dummy IoT Devices service:
7166

72-
If the proxy is correctly configured to connect to the Twitter API, a series of Tweets will be returned.
67+
- `DUMMY_DEVICES_PORT` - Port where the Dummy Devices service is running. Default: `3001`.
68+
- `DUMMY_DEVICES` - Full URL of the Dummy Devices service. Default: `http://localhost:${DUMMY_DEVICES_PORT}`.
69+
- `MOVE_TRACTOR` - Interval (in ms) to auto-move tractors (simulation). Default: `10000`.
70+
- `DUMMY_OFF` - If `true`, disables dummy device updates/interaction from this app. Default: `false`.
7371

74-
The Twitter API uses OAuth2:
75-
76-
- To get Consumer Key & Consumer Secret for the Twitter API, you have to create an app in Twitter via
77-
[https://developer.twitter.com/](https://developer.twitter.com/). Then you'll be taken to a page containing
78-
Consumer Key & Consumer Secret.
79-
- For more information see: [https://developer.twitter.com/](https://developer.twitter.com/)
80-
81-
- `/weather/health` A non-error response shows that an NGSI proxy for the Weather API is available on the network and
82-
returning values.
83-
84-
If the proxy is correctly configured to connect to the Open Weather Map API, the current weather in Berlin will be
85-
returned.
86-
87-
Most of the Weather API features require an API key.
88-
89-
- Sign up for a key at [`https://openweathermap.org/api`](https://openweathermap.org/api)
90-
- For more information see: [`https://openweathermap.org/appid`](https://openweathermap.org/appid)
91-
92-
## Keys and Secrets
93-
94-
All Keys and Secrets must be passed in using Environment variables. The following variables **must** be provided
95-
96-
- `OPENWEATHERMAP_KEY_ID=<ADD_YOUR_KEY_ID>`
97-
- `TWITTER_CONSUMER_KEY=<ADD_YOUR_CONSUMER_KEY>`
98-
- `TWITTER_CONSUMER_SECRET=<ADD_YOUR_CONSUMER_SECRET>`
99-
100-
---
10172

10273
## License
10374

104-
MIT © 2020-2026 FIWARE Foundation e.V.
75+
[MIT](LICENSE) © 2020-2026 FIWARE Foundation e.V.
10576

10677
See the LICENSE file in the root of this project for license details.
10778

10879
The Program includes additional icons downloaded from www.flaticon.com which were obtained under license:
10980

11081
- Smashicons - [https://www.flaticon.com/authors/smashicons](https://www.flaticon.com/authors/smashicons) - CC 3.0 BY
111-
- Those Icons - [https://www.flaticon.com/authors/those-icons](https://www.flaticon.com/authors/those-icons) - CC 3.0
112-
BY
82+
- Those Icons - [https://www.flaticon.com/authors/those-icons](https://www.flaticon.com/authors/those-icons) - CC 3.0 BY
11383
- Freepik - [http://www.freepik.com/](http://www.freepik.com/) - CC 3.0 BY
11484
- Bootstrap - [https://github.com/twbs/icons](https://github.com/twbs/icons) - MIT

‎iot-devices/README.md‎

Lines changed: 65 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -3,31 +3,79 @@
33
[![NGSI LD](https://img.shields.io/badge/NGSI-LD-d6604d.svg)](https://cim.etsi.org/NGSI-LD/official/front-page.html)
44
[![JSON LD](https://img.shields.io/badge/JSON--LD-1.1-f06f38.svg)](https://w3c.github.io/json-ld-syntax/)
55

6-
Simple nodejs express application for use with the FIWARE Step-by-Step tutorials.
6+
This is a Node.js Express application used to simulate IoT devices for the FIWARE Step-by-Step tutorials. It can mimic various devices (e.g., sensors, actuators) and supports communication over HTTP and MQTT using different payload formats (Ultralight, JSON, XML).
77

8-
This application provides sends information about devices on the farm.
8+
## Features
99

10-
### Actuators
10+
* **Device Simulation**: Simulates various IoT devices like:
11+
* **Motion Sensor**: Detects motion.
12+
* **Lamp**: Reports luminosity.
13+
* **Water Sprinkler**: Actuator to turn water on/off.
14+
* **Tractor**: Actuator to start/stop a tractor.
15+
* **Filling Station**: Actuator to fill/remove contents.
16+
* **Animal Collars**: Reports animal location and status.
17+
* **Multi-Protocol Support**: Can communicate via **HTTP** (Southbound commands) or **MQTT** (Northbound measurements and Southbound commands).
18+
* **Payload Formats**: Supports multiple payload formats configurable via environment variables:
19+
* `ultralight` (default)
20+
* `json`
21+
* `xml`
22+
* `lorawan` (placeholder)
23+
* `sigfox` (placeholder)
24+
* **Event Emission**: Emits events to the Tutorial Web App to visualize device actions.
25+
* **Security**: Integration with Keyrock IDM for OAuth2 token management.
1126

12-
- POST `/iot/water:id` - Actuate the water sprinkler on/off
13-
- POST `/iot/tractor:id` - Actuate the tractor start/stop
14-
- POST `/iot/filling:id` - Actuate the filling level add/remove/fill
27+
## API Endpoints
1528

16-
### Fire devices
29+
### Actuators (Southbound HTTP)
1730

18-
- GET `/status` - send the status of the weather and the barn door
19-
- GET `/devices/:type` - send the status of devices of a given type
20-
- GET `/animals` - send the status of the animal collars
31+
- `POST /iot/water:id` - Turn water sprinkler on/off.
32+
- `POST /iot/tractor:id` - Start/Stop tractor.
33+
- `POST /iot/filling:id` - Add/remove/fill filling level.
2134

22-
### Set device states
35+
### Device State & Information
2336

24-
- PUT `/devices/tractor` - - update the status of tractors
25-
- PUT `/devices` - initialise the cache of all devices
26-
- PUT `/barndoor` - toggle the barn door open/shut
27-
- PUT `/weather` - amend the weather - sunny/cloudy/raining
28-
- PUT `/temperature/:id` - amend the target temperature of a device
37+
- `GET /status` - Get status of weather and barn door.
38+
- `GET /devices/:type` - Get status of devices of a specific type.
39+
- `GET /animals` - Get status of animal collars.
2940

30-
To run the application in debug mode add `DEBUG=devices:*`
41+
### Control & Simulation (Northbound/Internal)
42+
43+
- `PUT /devices/tractor` - Update tractor status.
44+
- `PUT /devices` - Initialize or update device cache.
45+
- `PUT /barndoor` - Toggle barn door open/shut.
46+
- `PUT /weather` - Change weather conditions (sunny/cloudy/raining).
47+
- `PUT /temperature/:id` - Change target temperature of a device.
48+
49+
## Environment Variables
50+
51+
The application is configured using the following environment variables:
52+
53+
### Core Configuration
54+
55+
- `DUMMY_DEVICES_PORT` - Port the application listens on. Default: `3001`.
56+
- `DEBUG` - Debug mode configuration. e.g., `devices:*`.
57+
- `HISTORY_LOG` - File path to log measures (if set).
58+
59+
### Device Configuration
60+
61+
- `DUMMY_DEVICES_TRANSPORT` - Transport protocol to use. Options: `HTTP`, `MQTT`. Default: `HTTP`.
62+
- `DUMMY_DEVICES_PAYLOAD` - Payload format to use. Options: `ultralight`, `json`, `xml`. Default: `ultralight`.
63+
- `DUMMY_DEVICES_API_KEYS` or `DUMMY_DEVICES_API_KEY` - API Key(s) for MQTT topics. Default: `1234`.
64+
65+
### Connectivity
66+
67+
- `MQTT_BROKER_URL` - URL of the MQTT Broker. Default: `mqtt://mosquitto`.
68+
- `WEB_APP_HOST` - Hostname of the Tutorial Web App to emit events to. Default: `localhost`.
69+
- `WEB_APP_PORT` - Port of the Tutorial Web App. Default: `3000`.
70+
71+
### Security (Keyrock IDM)
72+
73+
- `KEYROCK_URL` - Public URL of the Keyrock IDM. Default: `http://localhost:3005`.
74+
- `KEYROCK_IP_ADDRESS` - Internal IP/URL of the Keyrock IDM. Default: `http://127.0.0.1:3005`.
75+
- `KEYROCK_PORT` - Port of the Keyrock IDM. Default: `3005`.
76+
- `KEYROCK_CLIENT_ID` - OAuth2 Client ID.
77+
- `KEYROCK_CLIENT_SECRET` - OAuth2 Client Secret.
78+
- `CALLBACK_URL` - OAuth2 Callback URL for the web app (referenced in security config).
3179

3280
---
3381

0 commit comments

Comments
 (0)