wirepas-wpe-apt 1.0.0

Tool to playback computed locations data

Wirepas WPE analysis and playback tool

This folder contain a module to analyse positioning results and playback of collected measurements.

The goals of this python library is to evaluate quickly the positioning setup: i.e. analyze positioning performance and generate a performance report.

Installation

This tool was originally created on python 3.8 but it is incompatible with 3.9+ due to thread comportement changes.

This library can be install from pypi directly with the following command: pip install wirepas_wpe_apt

Backend version

The WPE APT library has been created to work with WNT version until 4.4 and WPE until 1.7. Users should not have to worry about their backend version as it is already handled by the tool itself. The tool has been tested with WNT versions 4.3 and 4.4 and WPE versions 1.6 and 1.7 but should work with previous versions.

Configuration

The user must be placing the exact positions of a few selected tags on the floor plans on their Wirepas Network Tool (aka WNT) backend and setting them as planning nodes with a new network id (the same network id for all those reference positions) and the same node id as the tag they are referencing. These reference positions are essential as they will be used to measure the errors on the computed positions of the tags by the Wirepas Positioning Engine. Note: A tag without reference position can have its data stored from the data collector, but the report generator will not be capable of generate KPI for it.

Furthermore, to access WNT data, you have to provide credentials in a json format to the scripts. Following parameters can be used:

Parameter	Description	Default value	Possible value
wnt_hostname	WNT hostname		Any string
wnt_username	WNT username		Any string
wnt_password	WNT password		Any string
influxdb_port	Port to be used to connect to the influx database	8886	Any integer
influxdb_ssl	Does the influx database uses ssl	True	True or False
influxdb_verify_ssl	Does the influx database uses ssl verification	True	True or False
influxdb_database	Database to be queried when request data from influxdb	"wirepas"	Any string
anchors_dataset	Name of the dataset to request anchors data	"node_metadata"	Any string
measurements_dataset	Name of the dataset to request measurements data	"location_measurement"	Any string
references_dataset	Name of the dataset to request reference data	"node_metadata"	Any string
locations_dataset	Name of the dataset to request computed locations data	"location_update"	Any string
ws_auth_port	Authentication service websocket port	8813	Any integer
ws_metadata_port	Metadata service websocket port	8812	Any integer
ws_rts_port	Real time situation service websocket port	8811	Any integer

A credentials configuration should look like:

example_configuration.json

{
    "wnt_hostname": "wnt_hostname",
    "wnt_username": "wnt_username",
    "wnt_password": "wnt_password",
    "influxdb_port": 8886,
    "influxdb_ssl": true,
    "influxdb_verify_ssl": true,
    "influxdb_database": "influxdb_database",

    "anchors_dataset": "node_metadata",
    "measurements_dataset": "location_measurement",
    "references_dataset": "node_metadata",
    "location_dataset": "location_update",

    "ws_auth_port": 8813,
    "ws_metadata_port": 8812,
    "ws_rts_port": 8811
}

Modules

The library is structured by modules that are dependant. Currently, a data collector allows to retrieve the data from a WNT backend. And the report generator takes those information to generate performance report of the Wirepas positioning system. As there are data dependencies, the different scripts will all write/read specific files from an input folder with the following generated structure at the end of the execution:

├── <folder_name>/
│   ├── data/  # Generated by the data collector
│   │   ├── computed_locations.json  # Results of the location computations of the tags by the Wirepas Positioning Engine (aka WPE).
│   │   ├── metadata.json  # Metadata retrieved from the websocket services (Areas and their colors in the WNT, floor plans and their images from the selected mesh network.)
│   │   ├── network_configuration.json  # Network configuration (Anchors data and measurements of the tags)
│   │   └── reference.json  # Data of the reference positions of the tags
│   ├── floor_plans_images/  # Generated by the report generator
│   │   ├── <floor plan id>.png  # Image of a floor plan
│   │   └── ...
│   ├── report/  # Generated by the report generator
│   │   ├── css_style_for_html_report.css  # css file to enhance the visibility of the html report.
│   │   ├── report.csv  # Comparisons of the locations in a csv format.
│   │   └── report.html  # Html report - Detailed analysis of the performance of the positioning system.

Data collector

The data collector is responsible for gathering tag computed locations, rssi measurements, configuration data (anchors position, areas, floors), and reference informations then store those in a standardized format. Moreover, it uses another module (areas websockets manager) to get backend token/session id and metadata from the different backend services. Once the data are collected, the data collector is storing those by type of data in a folder that will be re used by the report generator module.

Execution

This command line lists all the possible parameters to launch the data collector script:

wirepas_apt_data_collector --help

This list of parameters can also be found below:

Parameter	Description	Default value	Possible value
configuration	Configuration file containing the backend credentials.		Any string
network_id	Network address of the tags to get data from.		Any integer (decimal and hexadecimal formats supported)
reference_network_id	Network address for the reference tags' positions.		Any integer (decimal and hexadecimal formats supported)
folder_path	Path of the folder to store the collected data.	"wpeapt_data"	Path of the folder to store the collected data.
node_list	List of nodes to get data from. If omitted, all tags of the selected mesh network will be queried.	None	A list string as follow: 1111,2222,3333 (decimal and hexadecimal formats supported)
time_start	Minimum UTC time of the data to be retrieved. It must have the ISO8601 format: "yyyy-MM-ddTHH:mm:ssZ". Example of input: "2024-07-10T8:00:00Z"	None	A string in ISO8601 format.
time_end	Maximum UTC time of the data to be retrieved. It must have the ISO8601 format: "yyyy-MM-ddTHH:mm:ssZ". Example of input: "2024-07-10T8:00:00Z"	None	A string in ISO8601 format.
reference_area_names_file	Name of a json file to map the reference positions of tags to their respective areas. When getting an area from a WNT backend, those are not linked to any areas. This option allow to fix this issue by providing a mapping between the node id (decimal and hexadecimal formats supported) of the reference positions and their area names. Example of content for this file: { "<Node id>": ["Area name"], "1": ["Area name 1"], "2": ["Area name 2"] }	None	Any string
query_anchors_from_rts	If provided, query anchors data from the Realtime Situation Service (aka RTS). Otherwise, it will get the anchor data from the Time series database (aka InfluxDB).	False
query_limit	Limit of data to retrieve when querying the computed data. It can be used to protect the database from doing huge queries.	10000	Any integer
log_level	Log level to be displayed.	'info'	"debug", "info", "warning", "error", "critical"
timeout_s	Timeout in seconds for each queries.	60	Any integer

And, here is an example to launch the data collector script from the command line:

wirepas_apt_data_collector --configuration <configuration> \
    --network_id <network_id> \
    --reference_network_id <reference_network_id> \
    --time_start "<time_start>" \
    --time_end "<time_end>" \
    --folder_path "<folder_path>" \
    [--query_anchors_from_rts]

Note:

The execution of the script generates logs both in the shell and in the file ./data_collector.log. Feel free to open the file to check again for some issue that might have happen.

Report Generator

Generate performance reports to analyse positioning data. It allows to evaluate quickly the positioning setup based on the data that were stored by the data collector. This means that this module must be executed after the data collector with the same data folder. The reports provide KPI such as computing the positioning error, area and floor match success for each tag analyzed. At the end of the execution, the user can open <folder_path>/report/report.html in their web browser to see the report.

Execution

This command line lists all the possible parameters to launch the report generator script :

wirepas_apt_report_generator --help

This list of parameters can also be found below:

Parameter	Description	Default value	Possible value
folder_path	Path of the folder to get the collected data and store the report.	"wpeapt_data"	Path of the folder to store the collected data.
marker_size	Size of anchor(s) / tag(s) marker in pixel	10	Any integer greater or equal to 1
time_start	Minimum UTC time of the computed locations present in the report. It must have the ISO8601 format: "yyyy-MM-ddTHH:mm:ssZ". Example of input: "2024-07-10T8:00:00Z"	None	A string in ISO8601 format.
time_end	Maximum UTC time of the computed locations present in the report. It must have the ISO8601 format: "yyyy-MM-ddTHH:mm:ssZ". Example of input: "2024-07-10T8:00:00Z"	None	A string in ISO8601 format.
log_level	Log level to be displayed.	'info'	"debug", "info", "warning", "error", "critical"

And, here is an example to launch the data collector script from the command line:

wirepas_apt_data_collector --folder_path "<folder_path>"

Note:

The execution of the script generates logs both in the shell and in the file ./report_generator.log. Feel free to open the file to check again for some issue that might have happen.