Code Documentation
ComDeX Prototype Code Function Documentation
The ComDeX prototype (which can be found here) is an NGSI-LD compliant “broker” that utilises a running MQTT broker. This documentation describes the functionality of the different methods used in the ComDeX codebase.
post_entity()
This function is used to create a new NGSI-LD entity in the ComDeX node.
Parameters:
data: The data of the entity to be created.my_area: The area or domain of the entity.broker: The name or IP address of the broker.port: The port number of the broker.qos: The quality of service level for message delivery.my_loc: The location of the broker (used for advanced advertisements with geoqueries).bypass_existence_check(optional): Flag to bypass the existence check of the entity (default: 0).client(optional): MQTT client object (default: mqtt.Client(clean_session=True)).
Returns:
- None
check_existence()
This function checks if an entity or advertisement already exists inside the broker.
Parameters:
broker: The name or IP address of the broker.port: The port number of the broker.topic: The topic name or identifier of the message to check.
Returns:
- True if the entity/advertisement exists in the broker, False otherwise.
GET()
This function is used to retrieve entities from the ComDeX node, similar to the NGSI-LD GET entities operation.
Parameters:
broker: The name or IP address of the broker.port: The port number of the broker.topics: A list of topics to subscribe to.expires: The expiration time in seconds.qos: The quality of service level for message delivery.limit(optional): The maximum number of entities to retrieve (default: 2000).
Returns:
- A list of received messages (entities) ordered via their id.
recreate_single_entity()
This function recreates a single entity from the received messages based on the specified query conditions. This is possible because each entity has a unique message id, which is used as the catalyst for the entity reconstruction from its various attribute messages.
Parameters:
messagez: List of received messages (entities).query: Query condition to filter the entities (optional, default: ‘’).topics: Topic filters to apply (optional, default: ‘’).timee: Time condition to filter the entities (optional, default: ‘’).georel: Geo-relation condition to filter the entities (optional, default: ‘’).geometry: Geometry type for the geospatial condition (optional, default: ‘’).coordinates: Coordinates for the geospatial condition (optional, default: ‘’).geoproperty: Geospatial property for the geospatial condition (optional, default: ‘’).context_given: Context value for entity comparison (optional, default: ‘’).
Returns:
- None
recreate_multiple_entities()
This function recreates multiple entities from the received messages based on the specified query conditions. It basically calls the recreate_single_entity command, over a list of MQTT messages, based on their id.
Parameters:
messagez: List of received messages (entities).query: Query condition to filter the entities (optional, default: ‘’).topics: Topic filters to apply (optional, default: ‘’).timee: Time condition to filter the entities (optional, default: ‘’).limit: Maximum number of entities to recreate (optional, default: 2000).georel: Geo-relation condition to filter the entities (optional, default: ‘’).geometry: Geometry type for the geospatial condition (optional, default: ‘’).coordinates: Coordinates for the geospatial condition (optional, default: ‘’).geoproperty: Geospatial property for the geospatial condition (optional, default: ‘’).context_given: Context value for entity comparison (optional, default: ‘’).
Returns:
- None
multiple_subscriptions()
This function sets up multiple subscriptions based on the specified flags and parameters.
Parameters:
entity_type_flag: Flag indicating whether entity type is specified.watched_attributes_flag: Flag indicating whether watched attributes are specified.entity_id_flag: Flag indicating whether entity ID is specified.area: Area value for the subscriptions.context: Context value for the subscriptions.truetype: Entity type value for the subscriptions.true_id: Entity ID value for the subscriptions.expires: Expiration time for the subscriptions.broker: MQTT broker address.port: MQTT broker port.qos: Quality of Service level for the subscriptions.watched_attributes: List of watched attributes for the subscriptions.
Returns:
- None
subscribe()
This function subscribes to MQTT topics and handles the received messages.
Parameters:
broker: MQTT broker address.port: MQTT broker port.topics: List of topics to subscribe to.expires: Expiration time for the subscriptions.qos: Quality of Service level for the subscriptions.context_given: Context value for entity comparison.
Returns:
- None
subscribe_for_advertisement_notification()
This function sets up subscriptions for advertisement notifications based on the specified flags and parameters, basically to find if a new advertisement of interest arrives while an interested subscriber is active (so that the subscriber while also connect to the new advertised source “on the fly”).
Parameters:
broker: MQTT broker address.port: MQTT broker port.topics: List of topics to subscribe to for advertisement notifications.expires: Expiration time for the subscriptions.qos: Quality of Service level for the subscriptions.entity_type_flag: Flag indicating whether entity type is specified.watched_attributes_flag: Flag indicating whether watched attributes are specified.entity_id_flag: Flag indicating whether entity ID is specified.watched_attributes: List of watched attributes for the subscriptions.true_id: Entity ID value for the subscriptions.
Returns:
- None
clear_retained()
This function clears the retained messages on the specified topic(s).
Parameters:
broker: MQTT broker address.port: MQTT broker port.retained: Single topic or list of topics to clear retained messages from.
Returns:
- None
Debug functions to see MQTT broker communication
on_message()
Callback function called when a message is received from the MQTT broker.
Parameters:
client: MQTT client instance.userdata: Custom userdata provided by the client.message: MQTT message object containing the received message.
Returns:
- None
on_log()
Callback function called when a log message is generated by the MQTT client.
Parameters:
client: MQTT client instance.userdata: Custom userdata provided by the client.level: Log level of the message.buf: Log message string.
Returns:
- None
usage()
This function displays help messages on how to use the command line interface, including the available options and some examples.
Returns:
- None
Usage: Usage: python actionhandler.py [options]
Options: -h, –help Show this help message and exit -c, –command Provide the command, possible commands include [POST/entities, POST/Subscriptions, DELETE/entities/, PATCH/entities/, GET/entities/, entityOperations/delete, entityOperations/create, entityOperations/update, entityOperations/upsert] -f, –file Specify the file to be used as input to the command -b, –broker_address Specify the address of the MQTT broker of the ComDeX node -p, –port Specify the port number of the MQTT broker of the ComDeX node -q, –qos Specify the Quality of Service level (0, 1, or 2) to be used for the specified command -H, –HLink Specify the HLink, ‘context link’ to be used for the GET request -A, –singleidadvertisement Specify if single ID advertisement is to be used (use 1 for True), default is false
Example: python3 actionhandler.py -c POST/entities -f entity.ngsild -b localhost -p 1026 -q 1 -H HLink -A 0
main()
This is the main function where different functions are called mainly based on the selected by the user command.
Parameters:
argv: command line arguments (see usage and tutorials for details)