Wirepas Services Tutorial

This step-by-step guide walks you through deploying the Wirepas stack to a fleet of edge devices using Orchestra.

Video Tutorial

Before You Begin

Make sure you have the following:

1. Active Orchestra Subscription: For details, see How to Get Orchestra.

2. Edge Devices Onboarded: Add your devices to Orchestra Manager (see How to add a Device) and ensure they run Orchestra Daemon (orchestrad) version 1.4.13 or higher (see Updating Orchestra Daemon).

3. Docker Engine Installed: Each edge device needs Docker Engine. Get it here: Install Docker Engine

4. Docker Compose File Prepared: Save the following YAML configuration as docker-compose.yml. We’ll use it shortly.

docker-compose.yml

version: "3.7"

volumes:
  dbus-volume:
    driver: local

services:
  dbus-service:
    image: wirepas/gateway_dbus_service:v1.4.5
    container_name: dbus-service
    restart: always
    volumes:
      - dbus-volume:/var/run/dbus
    logging:
      driver: journald
  transport-wbs-service:
    image: wirepas/gateway_transport_service:v1.4.5
    container_name: transport-wbs-service
    environment:
      WM_GW_ID: --will-be-overridden--
      WM_GW_MODEL: --will-be-overridden--
      WM_GW_VERSION: --will-be-overridden--
      WM_SERVICES_MQTT_HOSTNAME: --will-be-overridden--
      WM_SERVICES_MQTT_PORT: --will-be-overridden--
      WM_SERVICES_MQTT_USERNAME: --will-be-overridden--
      WM_SERVICES_MQTT_PASSWORD: --will-be-overridden--
    restart: always
    depends_on:
      - dbus-service
    volumes:
      - dbus-volume:/var/run/dbus
    logging:
      driver: journald
  sink-service:
    image: wirepas/gateway_sink_service:v1.4.5
    container_name: sink-service
    restart: always
    privileged: true
    depends_on:
      - dbus-service
    environment:
      WM_GW_SINK_BAUDRATE: 125000
      WM_GW_SINK_ID: 1
      WM_GW_SINK_UART_PORT: --will-be-overridden--
    volumes:
      - dbus-volume:/var/run/dbus
    logging:
      driver: journald

5. Gather Variables: You’ll need values for these variables during the deployment process.

   • WM_SERVICES_MQTT_USERNAME

   • WM_SERVICES_MQTT_PASSWORD

   • WM_SERVICES_MQTT_HOSTNAME

   • WM_SERVICES_MQTT_PORT

   • WM_GW_MODEL

   • WM_GW_VERSION

   • WM_GW_ID

Deployment Steps

We’ll divide the deployment into several key stages.

Step 1: Create a New Fleet

Fleets group your devices for easier management. Here’s how to set one up:

1. Open Orchestra Manager: Navigate to Orchestra Manager in your web browser.

2. Go to Fleets: Use the sidebar and click on “Fleets.”

   

3. Add a New Fleet: Click the “Add” button in the top-right corner.

4. Configure the Fleet: Give your fleet a descriptive name and select the target devices for your Wirepas deployment.

   

   Once created, your fleet will be visible:

   

Step 2: Create a Composition

Think of a composition as the blueprint for your application.

1. Navigate to Compositions: In the sidebar, click on “Compositions.”

   

2. Create a Composition: Click “Add” (top-right) and provide a name for your composition in the dialog box.

   

Step 3: Create the First Composition Version

Each composition can have multiple versions, allowing you to manage updates effectively.

1. Start Version Creation: Click “Create first version” on the composition page.

   

2. Specify Version: Use semantic versioning (e.g., 1.0.0) for clarity.

3. Upload Docker Compose: Select the docker-compose.yaml file you prepared earlier.

   

   You’ll now see an overview of your composition with the uploaded file:

   

Step 4: Attach Composition to the Fleet

Now, let’s link your composition to the target fleet of devices.

1. Go to Your Fleet: Navigate back to the fleet you created in Step 1.

2. Add the Composition: In the “Compositions” table, click “Add”.

   

3. Select the Composition: Choose your newly created composition from the dropdown.

   

Step 5: Setting Variables at the Composition Level

Variables provide customization for your deployment.

• Variable Scopes in Orchestra: Understand the hierarchy:

  • Device: Unique to a single device.

  • Fleet: Applies to all devices within a fleet.

  • Composition: Specific to an application composition.

  • Global: Universal settings across all devices and compositions.

• Inheritance: Variables inherit values from broader scopes:

  Global > Composition > Fleet > Device (More specific settings override broader ones).

Add Composition Variables:

1. Go to the “Variables” tab of your composition.

   

2. Click “Add” to introduce a new variable.

3. Start with WM_SERVICES_MQTT_HOSTNAME – provide your actual hostname as the value.

   

4. Repeat the process to add these variables, providing their values:

   • WM_SERVICES_MQTT_USERNAME

   • WM_SERVICES_MQTT_PASSWORD

   • WM_SERVICES_MQTT_PORT

Step 6: Fleet-Level Variables

For environmental variables common to all devices in the fleet:

1. Go to Fleet Variables: Navigate to your fleet and open the “Variables” tab.

2. Observe Inheritance: Notice how the composition-level variables are already present due to inheritance.

3. Add Fleet-Specific Variables: Introduce:

   • WM_GW_MODEL

   • WM_GW_VERSION

   

Step 7: Device-Level Variables

If needed, set individual device variables:

1. Go to Device Variables: Navigate to a device within your fleet and access its “Variables” tab.

2. Confirm Inheritance: Check if the variables from the fleet and composition levels are correctly inherited.

3. Add Gateway ID: Add the WM_GW_ID variable, specific to this device.

4. Add another device-level variable: WM_GW_SINK_UART_PORT for example value can be /dev/tty/ACM0.

5. Repeat for Other Devices: Assign a unique WM_GW_ID to each device in your fleet.

   

Step 8: Release Your Composition

Time to deploy!

1. Go to Compositions: On your fleet page, open the “Compositions” tab.

   

2. Select and Release: Choose your Wirepas composition and click “Create new release”.

   

   Orchestra will begin deploying your composition to all devices in the fleet:

   

Checking Deployment Success

1. Go to Device Details: On your fleet’s “Compositions” tab, click a device’s ID to see its details.

2. Open Terminal: In the device details, go to the “Terminal” tab and start a new terminal session.

3. List Containers: Run the command docker ps to view active containers. This confirms successful deployment.

Next steps

Next, you can Configuring Sink via CLI on Gateway.

Need Help?

Reach out through our Customer Portal if you encounter any issues.