# 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
```bash
{
"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:
```bash
├── <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:<br>{<br>"\<Node id\>": ["Area name"],<br>"1": ["Area name 1"],<br>"2": ["Area name 2"]<br>}<br> | 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:
```shell
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 report generator script from the command line:
```shell
wirepas_apt_report_generator --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.
Raw data
{
"_id": null,
"home_page": null,
"name": "wirepas-wpe-apt",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "Wirepas wpe playback apt",
"author": "Wirepas Ltd",
"author_email": "opensource@wirepas.com",
"download_url": "https://files.pythonhosted.org/packages/a3/98/36bd22e7515b3333ff053af89735fda69ce1aeb73e7f7b23d44d0228b021/wirepas_wpe_apt-1.0.1.tar.gz",
"platform": null,
"description": "# Wirepas WPE analysis and playback tool\n\nThis folder contain a module to analyse positioning results and playback of collected measurements.\n\nThe goals of this python library is to evaluate quickly the positioning setup: i.e. analyze positioning performance and generate a performance report.\n\n\n## Installation\n\nThis tool was originally created on python 3.8 but it is incompatible with 3.9+\ndue to thread comportement changes.\n\nThis library can be install from pypi directly with the following command:\n`pip install wirepas_wpe_apt`\n\n\n## Backend version\n\nThe WPE APT library has been created to work with WNT version until 4.4 and WPE until 1.7.\nUsers should not have to worry about their backend version as it is already handled by the tool itself.\nThe 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.\n\n\n## Configuration\n\nThe 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\nwith a new network id (the same network id for all those reference positions) and the same node id as the tag they are referencing.\nThese 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.\nNote: 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.\n\nFurthermore, to access WNT data, you have to provide credentials in a json format to the scripts.\nFollowing parameters can be used:\n\n| Parameter | Description | Default value | Possible value |\n| ----- | ---------- | ----- | ----- |\n| wnt_hostname | WNT hostname | | Any string |\n| wnt_username | WNT username | | Any string |\n| wnt_password | WNT password | | Any string |\n| influxdb_port | Port to be used to connect to the influx database | 8886 | Any integer |\n| influxdb_ssl | Does the influx database uses ssl | True | True or False |\n| influxdb_verify_ssl | Does the influx database uses ssl verification | True | True or False |\n| influxdb_database | Database to be queried when request data from influxdb | \"wirepas\" | Any string |\n| anchors_dataset | Name of the dataset to request anchors data | \"node_metadata\" | Any string |\n| measurements_dataset | Name of the dataset to request measurements data | \"location_measurement\" | Any string |\n| references_dataset | Name of the dataset to request reference data | \"node_metadata\" | Any string |\n| locations_dataset | Name of the dataset to request computed locations data | \"location_update\" | Any string |\n| ws_auth_port | Authentication service websocket port | 8813 | Any integer |\n| ws_metadata_port | Metadata service websocket port | 8812 | Any integer |\n| ws_rts_port | Real time situation service websocket port | 8811 | Any integer |\n\nA credentials configuration should look like:\n\nexample_configuration.json\n```bash\n{\n \"wnt_hostname\": \"wnt_hostname\",\n \"wnt_username\": \"wnt_username\",\n \"wnt_password\": \"wnt_password\",\n \"influxdb_port\": 8886,\n \"influxdb_ssl\": true,\n \"influxdb_verify_ssl\": true,\n \"influxdb_database\": \"influxdb_database\",\n\n \"anchors_dataset\": \"node_metadata\",\n \"measurements_dataset\": \"location_measurement\",\n \"references_dataset\": \"node_metadata\",\n \"location_dataset\": \"location_update\",\n\n \"ws_auth_port\": 8813,\n \"ws_metadata_port\": 8812,\n \"ws_rts_port\": 8811\n}\n```\n\n\n## Modules\n\nThe library is structured by modules that are dependant.\nCurrently, a data collector allows to retrieve the data from a WNT backend.\nAnd the report generator takes those information to generate performance report of the Wirepas positioning system.\nAs 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:\n\n\n```bash\n\u251c\u2500\u2500 <folder_name>/\n\u2502 \u251c\u2500\u2500 data/ # Generated by the data collector\n\u2502 \u2502 \u251c\u2500\u2500 computed_locations.json # Results of the location computations of the tags by the Wirepas Positioning Engine (aka WPE).\n\u2502 \u2502 \u251c\u2500\u2500 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.)\n\u2502 \u2502 \u251c\u2500\u2500 network_configuration.json # Network configuration (Anchors data and measurements of the tags)\n\u2502 \u2502 \u2514\u2500\u2500 reference.json # Data of the reference positions of the tags\n\u2502 \u251c\u2500\u2500 floor_plans_images/ # Generated by the report generator\n\u2502 \u2502 \u251c\u2500\u2500 <floor plan id>.png # Image of a floor plan\n\u2502 \u2502 \u2514\u2500\u2500 ...\n\u2502 \u251c\u2500\u2500 report/ # Generated by the report generator\n\u2502 \u2502 \u251c\u2500\u2500 css_style_for_html_report.css # css file to enhance the visibility of the html report.\n\u2502 \u2502 \u251c\u2500\u2500 report.csv # Comparisons of the locations in a csv format.\n\u2502 \u2502 \u2514\u2500\u2500 report.html # Html report - Detailed analysis of the performance of the positioning system.\n```\n\n\n### Data collector\n\nThe data collector is responsible for gathering tag computed locations, rssi measurements,\nconfiguration data (anchors position, areas, floors), and reference informations then store those in a standardized format.\nMoreover, it uses another module (areas websockets manager) to get backend token/session id and metadata from the different backend services.\nOnce 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.\n\n\n#### Execution\n\nThis command line lists all the possible parameters to launch the data collector script:\n\n`wirepas_apt_data_collector --help`\n\n\nThis list of parameters can also be found below:\n\n| Parameter | Description | Default value | Possible value |\n| ----- | ---------- | ---- | --- |\n| configuration | Configuration file containing the backend credentials. | | Any string |\n| network_id | Network address of the tags to get data from. | | Any integer (decimal and hexadecimal formats supported) |\n| reference_network_id | Network address for the reference tags' positions. | | Any integer (decimal and hexadecimal formats supported) |\n| folder_path | Path of the folder to store the collected data. | \"wpeapt_data\" | Path of the folder to store the collected data. |\n| 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) |\n| 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. |\n| 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. |\n| 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:<br>{<br>\"\\<Node id\\>\": [\"Area name\"],<br>\"1\": [\"Area name 1\"],<br>\"2\": [\"Area name 2\"]<br>}<br> | None | Any string |\n| 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 | |\n| 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 |\n| log_level | Log level to be displayed. | 'info' | \"debug\", \"info\", \"warning\", \"error\", \"critical\" |\n| timeout_s | Timeout in seconds for each queries. | 60 | Any integer |\n\n\nAnd, here is an example to launch the data collector script from the command line:\n\n```shell\nwirepas_apt_data_collector --configuration <configuration> \\\n --network_id <network_id> \\\n --reference_network_id <reference_network_id> \\\n --time_start \"<time_start>\" \\\n --time_end \"<time_end>\" \\\n --folder_path \"<folder_path>\" \\\n [--query_anchors_from_rts]\n```\n\nNote:\n\nThe execution of the script generates logs both in the shell and in the file `./data_collector.log`.\nFeel free to open the file to check again for some issue that might have happen.\n\n\n### Report Generator\n\nGenerate 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.\nThis means that this module must be executed after the data collector with the same data folder.\nThe reports provide KPI such as computing the positioning error, area and floor match success for each tag analyzed.\nAt the end of the execution, the user can open <folder_path>/report/report.html in their web browser to see the report.\n\n#### Execution\n\nThis command line lists all the possible parameters to launch the report generator script :\n\n`wirepas_apt_report_generator --help`\n\n\nThis list of parameters can also be found below:\n\n| Parameter | Description | Default value | Possible value |\n| ----- | ---------- | ---- | --- |\n| 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. |\n| marker_size | Size of anchor(s) / tag(s) marker in pixel | 10 | Any integer greater or equal to 1 |\n| 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. |\n| 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. |\n| log_level | Log level to be displayed. | 'info' | \"debug\", \"info\", \"warning\", \"error\", \"critical\" |\n\n\nAnd, here is an example to launch the report generator script from the command line:\n\n```shell\nwirepas_apt_report_generator --folder_path \"<folder_path>\"\n```\n\nNote:\n\nThe execution of the script generates logs both in the shell and in the file `./report_generator.log`.\nFeel free to open the file to check again for some issue that might have happen.\n",
"bugtrack_url": null,
"license": "Apache-2",
"summary": "Tool to playback computed locations data",
"version": "1.0.1",
"project_urls": null,
"split_keywords": [
"wirepas",
"wpe",
"playback",
"apt"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a39836bd22e7515b3333ff053af89735fda69ce1aeb73e7f7b23d44d0228b021",
"md5": "e5fe4a93c2a41db515ddcdf5d5121065",
"sha256": "91bd7e5ae1cc9b756f449f24770ba0e651aa7f8bbba462a794b27d4ea8ce73df"
},
"downloads": -1,
"filename": "wirepas_wpe_apt-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "e5fe4a93c2a41db515ddcdf5d5121065",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 66271,
"upload_time": "2024-08-05T14:01:04",
"upload_time_iso_8601": "2024-08-05T14:01:04.528191Z",
"url": "https://files.pythonhosted.org/packages/a3/98/36bd22e7515b3333ff053af89735fda69ce1aeb73e7f7b23d44d0228b021/wirepas_wpe_apt-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-05 14:01:04",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "wirepas-wpe-apt"
}
JSON