.. _working-with-wirepas: Working with Wirepas (2.4 GHz) =================================== If your device variant is installed with the CTHINGS.CO Mini-PCIe or M.2 Wirepas (2.4 GHz) extension cards or external Wirepas sink device over USB, it may be used as a gateway for the Wirepas mesh network. Generally, a working Wirepas (2.4 GHz) network consists of the following components: 1. At least one gateway with an internet or intranet backhaul equipped with a Wirepas *sink* device 2. *Wirepas Gateway Services* running on the gateway(s) on the network 3. *Wirepas Backend Services* running in the cloud or on-premise servers 4. Wirepas mesh network installed on-site with multiple *anchor* devices and, optionally, *tracker* devices CTHINGS.CO's Wirepas-enabled gateways can be delivered with any Wirepas sink firmware version of your choice. It is imperative to verify whether the sink firmware version is compatible with your installation of Wirepas Backend Services. If your application requires specific authentication/cipher keys (for Over-The-Air update functionality) or special firmware, get in touch with our support team. Additionally, CTHINGS.CO is able to provide a preloaded DFU bootloader with in-system programming capabilities as well as pre-installed and pre-configured options for Wirepas Gateway Services. Installing Wirepas Gateway Services ------------------------------------ Prerequisites """""""""""""""""""" * Understanding of the Wirepas software ecosystem and functioning installation of Wirepas Backend Services * Gateway networking configured with a route to the Wirepas Backend Services' server over the internet or intranet * Administrative privileges to the device * Console access to the device (monitor/keyboard/mouse, serial, SSH, or over Orchestra) Considerations """""""""""""""""""" In the following installation example, we assume the simple use case with a single sink and single transport (`single_transport`). If your application requires transmissions to two distinct Wirepas backends (`dual_transport`), the `docker-compose` configuration files may vary accordingly. This section is provided as a convenient "quick start" for Wirepas. For production use cases, we highly recommend referring to Wirepas' documentation. Steps """""""""" 1. Get the latest (or latest relevant to your installation of Wirepas Backend Services and WNT) version of the Wirepas Gateway Services archive from the "Releases" tab of `Wirepas' official GitHub repository `_. 2. Unzip the package if needed: .. code:: console $ unzip FILENAME.zip 3. Enter the unzipped directory (note that the folder name after decompression may change depending on the software version; in this case, it's `gateway-1.4.2`): .. code:: console $ cd gateway-1.4.2 4. Navigate to the directory containing the correct `docker-compose.yml` configuration file for your application (here, we assume `single_transport` operation): .. code:: console $ cd docker/docker-compose/single_transport/ 5. Edit the configuration file with a text editor of your choice: .. code:: console $ nano docker-compose.yml 6. The key variables to be changed in this file are (keep in mind that these variables may change in future versions or may be different if you are using another mode of operation) listed below. A full list of available parameters may be found in `Wirepas' official GitHub documentation `_ for `docker-compose` installations. * `WM_GW_ID`: A unique identifier for your gateway (it must be unique throughout your entire Wirepas network) * `WM_GW_MODEL`: Information about gateway type or model * `WM_GW_VERSION`: Information about gateway version * `WM_SERVICES_MQTT_HOSTNAME`: MQTT hostname of Wirepas Backend Services * `WM_SERVICES_MQTT_PORT`: MQTT port of Wirepas Backend Services * `WM_SERVICES_MQTT_USERNAME`: MQTT username of Wirepas Backend Services * `WM_SERVICES_MQTT_PASSWORD`: MQTT password of Wirepas Backend Services * `WM_GW_SINK_BAUDRATE`: Baudrate for serial communication sink (usually `125000`) * `WM_GW_SINK_ID`: A unique identifier for the connected sink (it must be unique throughout your entire Wirepas network) * ``services.sink-service.devices``: TTY device associated with the connected sink (usually `/dev/ttyACM0`); you can find this information using the commands `usb-devices` or `lsusb` * An exemplary configuration is provided for reference below. Do **NOT** copy this configuration as it may not be appropriate for the version of Wirepas software you are using. .. include:: ../../../shared/wirepas-docker-compose.rst 7. If your Linux distribution did not come with `compose` (and `docker`), install it using your distribution's package manager. CTHINGS.CO's Debian Linux releases generally come pre-installed with Docker and the `compose` plugin. It is recommended to refer to the official Docker documentation for installation instructions or the documentation from your device's manufacturer. 8. Finally, start Wirepas Gateway Services. Setting the `GATEWAY_TAG` is optional, but recommended. It should equal the same version concerning the `docker-compose.yml` configuration (and respective Wirepas Backend Services release on GitHub). Other tags may be explored on Wirepas' official Docker Hub repository. .. code:: console $ GATEWAY_TAG=v1.4.2 docker compose up -d 9. If no errors were reported, Wirepas Gateway Services should have successfully started. The containers will be brought up automatically after a reboot. .. note:: To see the logs associated with the service (this command must be run in the same directory as the `docker-compose.yml` configuration file): .. code:: console $ docker compose logs .. note:: To stop the service (this command must be run in the same directory as the `docker-compose.yml` configuration file): .. code:: console $ docker compose down Configuring Wirepas sink over CLI ------------------------------------ It is quite useful to be able to update sink configuration and parameters directly from the console of the gateway. This section illustrates the use of Wirepas' Gateway Services' Docker containers to issue configuration change commands to connected Wirepas sinks. Prerequisites """""""""""""""""""" * Understanding of the Wirepas software ecosystem * Wirepas Gateway Services' Docker containers installed on the device * Administrative privileges to the device * Console access to the device (monitor/keyboard/mouse, serial, SSH, or over Orchestra) Identifying the `dbus` volume """""""""""""""""""""""""""""""" 1. Identify the name of the Docker volume associated with Wirepas Gateway Services' `dbus` service. In this example, it is called `docker-compose_dbus-volume`. To find it, use (on some systems, you may need to use `sudo`): .. tab-set:: .. tab-item:: Command .. code:: console $ docker volume ls | grep "dbus" .. tab-item:: Output .. code:: console :class: no-copybutton local docker-compose_dbus-volume Obtaining the sink identifier """""""""""""""""""""""""""""""" The sinks that are connected to the device and their respective configurations can be obtained by executing the following command (replace `` with the correct value obtained above): .. tab-set:: .. tab-item:: Command .. code:: console $ docker run --rm -v :/var/run/dbus wirepas/gateway_transport_service wm-node-conf list .. tab-item:: Output .. code:: console :class: no-copybutton List of sinks:============== [sink1] =============== [sink_id]: sink1 [started]: True [node_address]: 1 [node_role]: SINK, CSMA_CA [network_address]: 5902971 [network_channel]: 12 [max_ac]: 8000 [min_ac]: 2000 [max_ac_cur]: 8000 [min_ac_cur]: 2000 [max_ch]: 40 [min_ch]: 1 [max_mtu]: 102 [hw_magic]: 6 [stack_profile]: 14 [firmware_version]: [5, 0, 2, 0] [app_config_max_size]: 80 [are_keys_set]: False [app_config_seq]: 20 [app_config_diag]: 60 [app_config_data]: =================================== The `sink_id` parameter (`sink1` in this particular example) obtained using this command is necessary to perform further get/set queries on a particular sink. Before setting sink parameters """""""""""""""""""""""""""""""""""" If you would like to edit/set sink parameters and it is already running (signified by the `[started]: True` in the command above), it must be stopped first. To do so, use the command for "Starting/Stopping the sink" defined below. Starting/Stopping the sink """""""""""""""""""""""""""""" Parameters: * ``: `dbus` volume name obtained above * ``: `true` or `false` to start/stop the sink * `sink_id`: Sink identifier obtained above Command: .. code:: console $ docker run --rm -v :/var/run/dbus wirepas/gateway_transport_service wm-node-conf set -S -s Setting the node address """""""""""""""""""""""""" Parameters: * ``: `dbus` volume name obtained above * ``: Integer number representing the address of the node you want to configure * `sink_id`: Sink identifier obtained above Command: .. code:: console $ docker run --rm -v :/var/run/dbus wirepas/gateway_transport_service wm-node-conf set -n -s Setting the node role """""""""""""""""""""""" Parameters: * ````: ``dbus`` volume name obtained above * ````: Role of the node as a string of any combination of the base role (``sink``, ``router``, or ``non-router``) and list of flags (``csma-ca`` and/or ``autorole``); example: ``-r "sink csma-ca"``, ``-r "router csma-ca autorole"``, etc. * ``sink_id``: Sink identifier obtained above .. code:: console $ docker run --rm -v :/var/run/dbus wirepas/gateway_transport_service wm-node-conf set -r -s Setting the network address """""""""""""""""""""""""""""" Parameters: * ````: ``dbus`` volume name obtained above * ````: Integer network address; example: ``-N 0xA1B2C3``, ``-N 123456``, etc. * ``sink_id``: Sink identifier obtained above .. code:: console $ docker run --rm -v :/var/run/dbus wirepas/gateway_transport_service wm-node-conf set -N -s Setting the network channel """""""""""""""""""""""""""" Parameters: * ````: ``dbus`` volume name obtained above * ````: Integer network channel; example: ``-c 5``, etc. * ``sink_id``: Sink identifier obtained above .. code:: console $ docker run --rm -v :/var/run/dbus wirepas/gateway_transport_service wm-node-conf set -c -s Setting the authentication key """""""""""""""""""""""""""""" Parameters: * ````: ``dbus`` volume name obtained above * ````: Network-wide 128-byte authentication key; example: ``-ak 112233445566778899AABBCCDDEEFF11``, ``-ak 11,22,33,44,55,66,77,88,99,AA,BB,CC,DD,EE,FF,11``, etc. * ``sink_id``: Sink identifier obtained above .. code:: console $ docker run --rm -v :/var/run/dbus wirepas/gateway_transport_service wm-node-conf set -ak -s Setting the cipher key """""""""""""""""""""" Parameters: * ````: ``dbus`` volume name obtained above * ````: Network-wide 128-byte cipher key; example: ``-ak 112233445566778899AABBCCDDEEFF11``, ``-ak 11,22,33,44,55,66,77,88,99,AA,BB,CC,DD,EE,FF,11``, etc. * ``sink_id``: Sink identifier obtained above .. code:: console $ docker run --rm -v :/var/run/dbus wirepas/gateway_transport_service wm-node-conf set -ck -s