Skip to content

Commit bbcf382

Browse files
dkastldkastl
committed
Doc updates
Signed-off-by: Daniel Kastl <[email protected]>
1 parent 2650a5b commit bbcf382

File tree

6 files changed

+222
-126
lines changed

6 files changed

+222
-126
lines changed

‎README.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
# Redmine GTT FIWARE Plugin
22

3-
The Geo-Task-Tracker (GTT) FIWARE plugin adds support for [FIWARE](https://www.fiware.org/)
4-
open standards:
3+
The Geo-Task-Tracker (GTT) FIWARE plugin adds support for interacting with [FIWARE](https://www.fiware.org/):
54

6-
- TBD
5+
- Create and publish FIWARE Context Broker subscriptions
6+
- Create and update issues based on FIWARE context data
7+
- Provide an NGSI API to interact with Redmine entities (read-only)
78

89
## Requirements
910

‎doc/curl_examples.md‎

Lines changed: 0 additions & 119 deletions
This file was deleted.

‎doc/examples/camera_sensor.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Speed Camera Sensor Example
2+
3+
This example demonstrates how to create a street camera sensor entity and
4+
subscribe to its updates.
5+
6+
## Creating an Entity with Speed Camera
7+
8+
```bash
9+
curl -iX POST "${BROKER_URL}/v2/entities" \
10+
-H "Content-Type: application/json" \
11+
-d '{
12+
"id": "urn:ngsi-ld:SpeedCameraSensor:001",
13+
"type": "SpeedCameraSensor",
14+
"image": {
15+
"value": "https://images.unsplash.com/photo-1567333188258-99e13c119241%3Fw%3D640",
16+
"type": "URL"
17+
},
18+
"speed": {
19+
"value": 87,
20+
"type": "Number"
21+
},
22+
"location": {
23+
"value": {
24+
"type": "Point",
25+
"coordinates": [135.27666, 34.72483]
26+
},
27+
"type": "geo:json"
28+
},
29+
"timestamp": {
30+
"value": "2021-09-01T12:00:00Z",
31+
"type": "DateTime"
32+
}
33+
}'
34+
```
35+
36+
## Update Speed
37+
38+
```bash
39+
curl -iX PATCH \
40+
"${BROKER_URL}/v2/entities/urn:ngsi-ld:SpeedCameraSensor:001/attrs" \
41+
-H "Content-Type: application/json" \
42+
-d '{
43+
"speed": {
44+
"value": 90.0,
45+
"type": "Number"
46+
}
47+
}'
48+
```
49+
50+
## Delete Entities
51+
52+
```bash
53+
curl -iX DELETE "${BROKER_URL}/v2/entities/urn:ngsi-ld:SpeedCameraSensor:001"
54+
```
55+
56+
## Notes
57+
58+
- Ensure that the FIWARE context broker is running and accessible.
59+
- The coordinates in the location examples are in [longitude, latitude] format.
60+
61+
These cURL commands should help you interact with the FIWARE broker and test the
62+
Redmine GTT FIWARE plugin effectively. If you encounter any issues or need
63+
further assistance, please let us know!

‎doc/examples/location_sensor.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Location Sensor Example
2+
3+
This example demonstrates how to create a location sensor entity and subscribe
4+
to its updates.
5+
6+
## Creating an Entity with Location
7+
8+
```bash
9+
curl -iX POST "${BROKER_URL}/v2/entities" \
10+
-H "Content-Type: application/json" \
11+
-d '{
12+
"id": "urn:ngsi-ld:LocationSensor:001",
13+
"type": "LocationSensor",
14+
"location": {
15+
"value": {
16+
"type": "Point",
17+
"coordinates": [135.27666, 34.72483]
18+
},
19+
"type": "geo:json"
20+
}
21+
}'
22+
```
23+
24+
## Update Location
25+
26+
```bash
27+
curl -iX PATCH \
28+
"${BROKER_URL}/v2/entities/urn:ngsi-ld:LocationSensor:001/attrs" \
29+
-H "Content-Type: application/json" \
30+
-d '{
31+
"location": {
32+
"value": {
33+
"type": "Point",
34+
"coordinates": [139.75032, 35.67087]
35+
},
36+
"type": "geo:json"
37+
}
38+
}'
39+
```
40+
41+
## Delete Entities
42+
43+
```bash
44+
curl -iX DELETE "${BROKER_URL}/v2/entities/urn:ngsi-ld:LocationSensor:001"
45+
```
46+
47+
## Notes
48+
49+
- Ensure that the FIWARE context broker is running and accessible.
50+
- The coordinates in the location examples are in [longitude, latitude] format.
51+
52+
These cURL commands should help you interact with the FIWARE broker and test the
53+
Redmine GTT FIWARE plugin effectively. If you encounter any issues or need
54+
further assistance, please let us know!

‎doc/examples/temperature_sensor.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Temperature Sensor Example
2+
3+
This example demonstrates how to create a temperature sensor entity and
4+
subscribe to its updates.
5+
6+
## Creating an Entity with Temperature
7+
8+
```bash
9+
curl -iX POST "${BROKER_URL}/v2/entities" \
10+
-H "Content-Type: application/json" \
11+
-d '{
12+
"id": "urn:ngsi-ld:TemperatureSensor:001",
13+
"type": "TemperatureSensor",
14+
"temperature": {
15+
"value": 25.0,
16+
"type": "Number"
17+
}
18+
}'
19+
```
20+
21+
## Update Temperature
22+
23+
```bash
24+
curl -iX PATCH \
25+
"${BROKER_URL}/v2/entities/urn:ngsi-ld:TemperatureSensor:001/attrs" \
26+
-H "Content-Type: application/json" \
27+
-d '{
28+
"temperature": {
29+
"value": 28.0,
30+
"type": "Number"
31+
}
32+
}'
33+
```
34+
35+
## Delete Entities
36+
37+
```bash
38+
curl -iX DELETE "${BROKER_URL}/v2/entities/urn:ngsi-ld:TemperatureSensor:001"
39+
```
40+
41+
### Get Entities
42+
43+
```bash
44+
curl -sX GET "${BROKER_URL}/v2/entities" -H "Accept: application/json" | jq
45+
```
46+
47+
### Get Subscriptions
48+
49+
```bash
50+
curl -sX GET "${BROKER_URL}/v2/subscriptions" -H "Accept: application/json" | jq
51+
```

‎doc/index.md‎

Lines changed: 50 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,17 +7,63 @@ FIWARE plugin and its API endpoints.
77

88
- Make sure REST web services is enabled: <http://localhost:3000/settings?tab=api>
99
- Enable the plugin in project settings
10+
- Don't select a user with admin rights for the FIWARE subscriptions. Instead,
11+
create a new user with the necessary permissions.
1012

11-
To allow **public** access to NGSI-LD context documents, it's necessary to grant
12-
*View* permissions to the *Anonymous* role.
13+
### Redmine Permissions
1314

1415
![Plugin permissions](permissions.png)
1516

16-
## Table of Contents
17+
To allow **public** access to NGSI-LD context documents, it's necessary to grant
18+
*View* permissions to the *Anonymous* role.
19+
20+
## How to use
1721

1822
- [Plugin Settings](plugin_settings.md)
1923
- [Project Settings](project_settings.md)
2024
- [Subscription Templates](subscription_template.md)
2125
- [API Endpoints](api_endpoints.md)
26+
27+
## Tools and Utilities
28+
2229
- [FIWARE Broker Scripts](broker_scripts.md)
23-
- [cURL Examples](curl_examples.md)
30+
31+
## Examples and Tutorials
32+
33+
- [Temperature Sensor Example](temperature_sensor.md)
34+
- [Location Sensor Example](location_sensor.md)
35+
- [Street Camera Sensor Example](camera_sensor.md)
36+
37+
For all examples, the following environment variables are used:
38+
39+
```bash
40+
export BROKER_URL="http://your_broker:1026"
41+
```
42+
43+
Replace `your_broker_url` with the actual URL of your FIWARE broker. After
44+
running this command, the BROKER_URL environment variable will be
45+
available to all subsequent commands in the same terminal session.
46+
47+
### General FIWARE Broker Commands
48+
49+
#### Get Entities
50+
51+
```bash
52+
curl -sX GET "${BROKER_URL}/v2/entities" -H "Accept: application/json" | jq
53+
```
54+
55+
#### Get Subscriptions
56+
57+
```bash
58+
curl -sX GET "${BROKER_URL}/v2/subscriptions" -H "Accept: application/json" | jq
59+
```
60+
61+
### Notes
62+
63+
- Ensure that the FIWARE context broker is running and accessible.
64+
- The coordinates in the location examples are in `[longitude, latitude]` format.
65+
- The `jq` command is used to format the JSON output for better readability.
66+
67+
These cURL commands should help you interact with the FIWARE broker and test the
68+
Redmine GTT FIWARE plugin effectively. If you encounter any issues or need
69+
further assistance, please let us know!

0 commit comments

Comments
 (0)