Installation & Administration Guide
Installation
To install and use the GCN, certain pre-requisites must be met. Although a docker-compose
file is provided, enabling quick start-up of the system in an example scenario, the following middlewares must be provided in a custom application:
- A MongoDB instance (v3.6+) is required for data storage.
- An Orion Context Broker instance allows to manage information by making use of entities that can be seen as objects in the context of object oriented programming. It manages all the changes regarding those entities and allows the broadcast of those changes to all the other components that are connected to Orion. There are a set of features that Orion makes available like the Publish/Subscribe or the registration of context providers to allow queries of information by demand.
- A Cygnus instance is used to interpret the NGSI v2 specification used by Orion and storing the context changes in each entity that is configured to be watched by Cygnus.
- A JSON IoT Agent instance is needed to enable the integration of IoT devices with all its characteristics in the Orion Context Broker. Additionally, it behaves as a converter between distinct communication protocols that Orion does not understand to HTTP requests understandable by Orion.
- An MQTT broker to allow all the components to communicate via MQTT messages by using a publish/subscribe model. An example using Eclipse Mosquitto is provided.
After checking all the necessary dependencies, clone the repository using the following command:
git clone https://github.com/Introsys/FIREFIT.ROSE-AP
Configuration
There are three files that need to be configured in order to use GCN:
configuration.json
- this JSON file holds all the necessary parameters to configure GCN and how it connects to other services.camera.py
- this Python file is responsible for holding all the necessary code to interact with the camera.Dockerfile
- this file is responsible for holding all the necessary elements to create a Docker image containing GCN.
Keep in mind the current limitations of GCN through the configuration process.
Configuration File
The configuration.json
file is located at the configuration
folder. Not only it defines how GCN will connect to other services but also how it is going to create the Image Reference Entity and the camera device.
An example of configuration is presented, where the endpoints make use of hostname
instead of ip address
for simplicity and convenience, since GCN is most likely to be used in a stack of docker containers.
{
"cb_endpoint": "http://orion:1026",
"cygnus_endpoint": "http://cygnus:5051",
"iota_endpoint": "http://iot-agent:4041",
"iota_protocol": "MQTT",
"protocol_broker_address": "mosquitto",
"protocol_broker_port": "1883",
"entity_id": "urn:ngsi-ld:ImageRecord:001",
"camera_id": "urn:ngsi-ld:Camera:001",
"api_key": "camera",
"service": "production",
"service_path": "ids",
"sink": "mongo",
"sink_endpoint": "mongodb://mongo-db:27017"
}
All parameters are mandatory, and a description of each is presented:
cb_endpoint
- the address (ip:port) of Orion Context Brokercygnus_endpoint
- the address (ip:port) of Cygnus, to which Orion will post HTTP messages toiota_endpoint
- the address (ip:port) of JSON IoT Agentiota_protocol
- the transport parameter to be defined for the JSON IoT Agent, note that it must be compliant with the acceptable parameters for the agent (HTTP
,MQTT
orAMPQ
)protocol_broker_address
- the address (ip) of the message broker for the protocol specified iniota_protocol
protocol_broker_port
- the port of the message broker for the protocol specified iniota_protocol
entity_id
- the id of the Image Reference Entity which will be created at Orion, it is advised by Fiware that it should respect the NGSI-LD specificationcamera_id
- the id of the generic device that will be created as a camera at JSON IoT Agent and, consequently, at Orion, following the same advice provided by Fiware regarding the NGSI-LD specificationapi_key
- a JSON IoT Agent specific configurationservice
- a JSON IoT Agent specific configuration, it will also specify the database to where images will be storedservice_path
- a JSON IoT Agent specific configuration, it will also specify the database collection to where images will be storedsink
- the type of sink to where images will be storedsink_endpoint
- the sink address
To understand the importance and role of the api_key
, service
and service_path
parameters, one should be familiar with how JSON IoT Agent operates.
Camera File
The camera.py
file presents the necessary structure to allow users to implement the desired operations to interact with the camera and it is located at the GCNLib
Python module.
It is imperative that the Python class structure is respected in order to GCN work properly.
import json
class Camera:
def __init__(self):
self.connection_exceptions = ()
pass
def connect(self):
pass
def disconnect(self):
pass
def initialize(self):
pass
def capture(self) -> str:
# MUST RETURN A JSON STRING
image = {
"filename": "example_image",
"image": "image_content"
}
return json.dumps(image)
def configure(self, parameters):
pass
Considering the rules applied by the Python programming language:
__init__
- class initialization, all the library specificExceptions
that will be defined in theself.connection_exceptions
parametertuple
will trigger an automatic reconnect attempt, each time the camera disconnects raising one of the specified exceptionsconnect
- necessary operations to connect to the cameradisconnects
- necessary operations to disconnect from the camerainitialize
- executed right after a successfulconnect
, allows to perform initialization processescapture
- necessary operations to capture an image, the return type must be aJSON string
containing afilename
andimage
keys, where the values are also of the typestring
. The return of this function will be sent to the specifiedsink
configure
- necessary operations to configure the camera, theparameters
provided as a function input correspond to the specified value when issuing the deviceconfigure
command
Usage
To use the GCN, navigate to the path where the repository was cloned and then to the component folder:
cd gcn
Execute the python application:
python gcn.py
Note: ensure that the component is configured and all pre-requisites are met.
Docker
Docker is the best way to use the GCN, as it is a common practice among other FIWARE services.
A pre-built image is located at docker hub for quick testing the component. To get this image, issue the following command:
docker pull introsyspt/gcn:latest
In real-world applications though, the user is required to extend the camera.py
module and change the default configuration to embrace its needs. After making all the configurations, one can use the Dockerfile
located at the root
directory to build a local image.
FROM python:3.8-slim-buster
WORKDIR /app
ADD . /app
RUN pip install -r requirements.txt
CMD ["python", "./cgn.py"]
To build the image, use the command:
docker build -t gcn .
If the pre-requisites are met, that is, all required services are execution, one can execute the image directly:
- Using the docker hub image
docker run introsyspt/gcn
- Using the local image
docker run gcn
Additionally, a docker-compose
file can be used to ramp-up the stack and start all the needed services at once.
To execute, issue the following command:
cd docker
docker-compose -p gcn_stack up
To terminate:
docker-compose gcn_stack down
Current Limitations
GCN presents the following limitations at the current stage:
- only accepts
MQTT
as value foriota_protocol
- only accepts
mongo
as value forsink
Previous: Architecture | Next: Getting Started