.. _om-wirepas-networks: ================ Wirepas networks ================ *This chapter describes what Wirepas networks are and how to create, manage and deploy them.* The **Wirepas networks** page allows you to configure and deploy gateway software that connects the Wirepas mesh to the server. Each network creates a composition that behaves like a blueprint for your Wirepas application that runs on your gateway. This composition is automatically assigned to the fleet of devices you connect your Wirepas network to. The **Wirepas networks** tab is in the sidebar, as shown in the following figure. .. image:: images/wirepas-networks-tab-in-sidebar.png :alt: Wirepas networks tab in the sidebar :width: 100% :align: center .. _om-wirepas-networks-before-you-start: Before you start ---------------- You'll need: * the Wirepas feature turned on in Marketplace. * your gateways equipped with the Wirepas Connectivity Card and onboarded. * the following values: * Wirepas Mesh MQTT username, password, hostname and port, * network ID and channel, * gateway stack version. .. TODO: link to Marketplace .. TODO: link to onboarding gateways .. warning:: The feature cannot be turned off in Marketplace until any network exists. .. _om-wirepas-networks-create: Create a Wirepas network ------------------------ Click the **+ Add network** button in the top right corner, and a pop-up appears. Follow the next 5 steps to create your network. .. _om-wirepas-networks-create-parameters: Configure the network parameters ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In the **Network parameters** step: 1. Give your network a name. 2. Provide the network ID and channel your Wirepas mesh works on. The ID must be exactly 8 hex characters, for example, ``A1B2C3D4``. 3. Give this network authentication and cipher keys. .. image:: images/wirepas-networks-creating-network-parameters.png :alt: Network parameters step of the Add network window :width: 100% :align: center .. important:: Keys are optional, but they play an important role in the security of your mesh. It is better to provide them. .. _om-wirepas-networks-create-sink-gateway: Set up the sink and gateway ~~~~~~~~~~~~~~~~~~~~~~~~~~~ In the **Sink & gateway settings** step, you can see the name of your sink. This field is read-only, but you can change the name of your sink later in the fleet's variables section; see :ref:`om-wirepas-networks-sink-name`. 1. Select the sink role. There are two possible options: .. list-table:: :header-rows: 1 :widths: 30 70 * - Role - Description * - ``sink csma-ca`` - Your sink is a place where data from the mesh leaves. * - ``router csma-ca autorole`` - Your sink behaves like a router in your mesh. 2. In the **Start stack after configuration** field, select either **True** or **False**. If set to **False**, after configuration, the stack does not start automatically. 3. In the last field, select the gateway stack version. .. image:: images/wirepas-networks-creating-network-sink-and-gateway-settings.png :alt: Sink & gateway settings step of the Add network window :width: 100% :align: center .. _om-wirepas-networks-create-host: Set the Wirepas host parameters ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In the **Wirepas host parameters** step, add the MQTT hostname, port, username and password that you gathered in :ref:`Before you start `. .. image:: images/wirepas-networks-creating-network-wirepas-host.png :alt: Wirepas host parameters step of the Add network window :width: 100% :align: center .. warning:: Providing incorrect data may lead to a gateway that fully works but does not send any information back to the broker. .. _om-wirepas-networks-create-fleet: Select a fleet ~~~~~~~~~~~~~~ In the **Fleet details** step: .. image:: images/wirepas-networks-creating-network-fleets-details.png :alt: Fleet details step of the Add network window :width: 100% :align: center If you already have a fleet with devices that should run your Wirepas network application: 1. Select this fleet from the dropdown menu. 2. Click the **Next** button. .. image:: images/wirepas-networks-creating-network-fleets-details-choosing-fleet.png :alt: Selecting an existing fleet in the Fleet details step :width: 100% :align: center If you onboarded devices but did not create the fleet: 1. Click **Create fleet**. 2. Provide the fleet's name. 3. Add devices. 4. Press **Next**. .. image:: images/wirepas-networks-creating-network-fleets-details-creating-fleet.png :alt: Creating a new fleet in the Fleet details step :width: 100% :align: center .. _om-wirepas-networks-create-summary: Check the summary ~~~~~~~~~~~~~~~~~ In the **Summary** step: .. image:: images/wirepas-networks-creating-network-summary.png :alt: Summary step of the Add network window :width: 100% :align: center .. important:: Check all values you have provided earlier very carefully. Providing wrong data leads to non-working applications .. TODO: confirm the final action: the screenshot shows an **Add** button in the Summary step The network is created. .. image:: images/wirepas-networks-created-network.png :alt: Created Wirepas network :width: 100% :align: center The next step is to deploy this network's application to your gateway. .. _om-wirepas-networks-composition: Wirepas network composition --------------------------- The **Go to composition** button is in the top right corner, as shown in the following figure. .. image:: images/wirepas-networks-go-to-compositions.png :alt: Network details page with the Go to composition button :width: 100% :align: center When you were creating the Wirepas network, the composition was automatically created and attached to the fleet. This composition contains four applications: .. list-table:: :header-rows: 1 :widths: 30 70 * - Application - Description * - ``dbus-service`` - A private D-Bus message bus the other services talk over. * - ``sink-service`` - Drives the USB sink over UART and exposes it on D-Bus. * - ``transport-service`` - The MQTT client. Uses the MQTT credentials you already specified to bridge D-Bus traffic to the broker. * - ``wirepas-configurator`` - Runs once. It finds the sink. After that, it stops it, writes the node address, role, network ID, channel and keys, then starts the sink again if **Start stack after configuration** is set to **True**. This composition has the same name as its Wirepas network. .. image:: images/wirepas-networks-network-composition.png :alt: Composition details page of the Wirepas network composition :width: 100% :align: center .. _om-wirepas-networks-deploy: Deploy the network stack ------------------------ You can deploy the automatically generated composition. The **Go to fleet** button is in the top right corner, as shown in the following figure. .. image:: images/wirepas-networks-go-to-fleet.png :alt: Go to fleet button on the Network details page :width: 100% :align: center Press it, and you are redirected to the previously connected fleet. .. image:: images/wirepas-networks-deploying-composition.png :alt: Compositions tab of the connected fleet :width: 100% :align: center TODO link to deploying a composition within a fleet ("For detailed information on how to deploy a composition within a fleet, see …") You can check the status of your deployment directly in the network tab, as shown in the following figure. .. image:: images/wirepas-networks-checking-composition-status.png :alt: Deployment status on the Network details page :width: 100% :align: center .. important:: Any changes you make to the network that affect the composition are not deployed automatically. They appear only after a redeployment or the deployment of a new version. .. _om-wirepas-networks-settings: Change the network settings --------------------------- The settings button is in the top right corner, as shown in the following figure. .. image:: images/wirepas-networks-setting-button.png :alt: Settings button on the Network details page :width: 100% :align: center In the settings, you can apply changes to your network. You can change: * network name, * network ID and channel, * authentication and cipher keys, * sink role, * **Start stack after configuration**, * gateway stack version, * host parameters (MQTT credentials), * fleet. .. image:: images/wirepas-networks-network-settings.png :alt: Network details window with the network settings :width: 100% :align: center .. _om-wirepas-networks-sink-name: Change the sink name ~~~~~~~~~~~~~~~~~~~~ In the **Sink & gateway settings** tab, you can see that the sink name is read-only. If you need to change it, follow the next steps: 1. Go to your network and open its fleet section: .. image:: images/wirepas-networks-go-to-fleet.png :alt: Go to fleet button on the Network details page :width: 100% :align: center 2. On the fleet page, open the **Variables** tab and find ``WM_GW_SINK_ID``. This is the variable that holds the sink name value. .. image:: images/wirepas-networks-changing-sink-id.png :alt: WM_GW_SINK_ID variable on the Variables tab of the fleet :width: 100% :align: center 3. Click it and change the value. 4. Save your new value. 5. Check the Wirepas network settings. Your new value should be visible.