Connect gateways running Bosch IoT Edge

images/confluence/download/attachments/1408857432/connect.svg

The Bosch IoT Suite allows connecting field gateways running Bosch IoT Edge, as well as all IoT devices that are connected to such field gateways.

The connection between the Bosch IoT Edge runtime and the cloud services uses the MQTT endpoint of Bosch IoT Hub.

This guide walks you through configuring and connecting a Linux-based device to the Suite services available in your subscription.

The connectivity of Linux-based devices is provided and ensured by the Edge Agent available for Debian-based Linux distributions for ARM (v7) and x86_64 platforms.

Download the Edge Agent

  1. Open the Service Subscriptions page of Bosch IoT Suite portal.

  2. Scroll to the corresponding package you subscribed.

  3. Click Edge Downloads to open the download page.

    images/confluence/download/attachments/1408857432/download-edge.png
  4. It may take, several minutes, to receive personalized Bosch IoT Edge downloads.
    Download the Edge Agent runtime (this example continues with the image for Linux).

    images/confluence/download/attachments/1408857432/download-edge-all.png

    The license is limited to 3 months after the subscription date.

    Advanced developers can build their own runtime image via the Bosch IoT Edge Service SDK by downloading the appropriate SDK.
    See Edge Services official documentation for details.

  5. Unpack the runtime on your local machine or directly on the field gateway.

Provision the Edge Agent as a gateway device

Create valid credentials for your Edge Agent. These are necessary to setup the connection to Bosch IoT Hub.

  1. Provisioning a gateway is pretty similar to the steps described at Provisioning of devices via developer console,
    except you can directly choose the option to set gateway-specific settings (see markers 3 and 4 on the screenshot).
    The ID must follow the pattern: <namespace>:<edge-agent-identifier> (see markers 5 and 6 on the screenshot).

    images/confluence/download/attachments/1408857432/dev-console-provision-GW.png

    If you prefer provisioning via API, find examples at Device provisioning via API.

  2. As soon as the Preview shows all markers green, proceed with Send request.

  3. Save the result of the device provisioning process to a file named provisioning.json.
    E.g. use the Save response button of the provisioning response. As soon as the Edge Agent will try to connect to the Bosch IoT Hub MQTT adapter, it will need properties stored in that file.

EXISTING CUSTOMERS who might need to migrate, please stick to the descriptions at https://docs.bosch-iot-suite.com/edge/index.html#110345.htm.

Prepare the Edge Agent with the provisioning credentials

Before you can successfully run the Bosch IoT Edge Agent to connect your device, you need to take several steps that will provide the right settings for your device.
Those settings are saved in a provisioning template that is a JSON document.

Upon the launch of the Bosch IoT Edge Agent, Bosch IoT Edge will automatically use the provisioning settings from the provisioning.json file to connect to the cloud service.

Unpack the runtime on your local machine or directly on the field gateway.

Upon multiple options this example continues with the option marked (tick)

  1. Each of the Edge Agent Linux distributions includes a set of Bash management scripts that are located in the root of the package:

    1. install.sh - downloads, installs and configures the Edge Agent images/confluence/s/lo86y3/8501/824f149d70ae2ad1d29a82a2fd43b16cca383892/_/images/icons/emoticons/check.svg
      core components (the edge containers management engine and the cloud connectivity enablement)
      and their relevant dependencies (containerd, Eclipse Mosquitto)

    2. start.sh - starts the Edge Agent

    3. stop.sh - stops the Edge Agent

    4. uninstall.sh - uninstalls the Edge Agent and all its installed dependencies (optionally and all the Edge Agent's persistent data).

      Alternatively, follow the description at https://docs.bosch-iot-suite.com/edge/index.html#109968.htm.

  2. Get familiar with the Edge Agent

    Now you have an installed a ready-to-connect Edge Agent on your target platform.

    All configurations made are persisted in an edge.config file. It is located in the same directory as the install script.

    To change the configurations later, edit the file and restart the Edge Agent for the new configurations to take effect.

  3. Start the Edge Agent with start.sh
    Starting the Edge Agent actually establishes the cloud connection based on the device credentials provided in the Bosch IoT Suite Console dialogue.

  4. Upon success, the agent will use the credentials from provisioning.json and

    1. connect automatically to the cloud service - using the MQTT adapter.
      Its certificate is already part of your folder.
      <com.bosch.iot.edge.agent.assemblies.dist-pack_linux_x86_64>\cloud.connector.generic\iothub.crt

    2. Further, a "digital twin" representation of the gateway and its resources will be automatically updated in the Bosch IoT Things service.

Congratulations,
these configurations are necessary only the first time you start your Edge Agent.

Check the representation at the Bosch IoT Suite Console

In case everything was successful, you should see the Edge Agent gateway and its resources in the Things view of the developer console.

In case you have booked the Device Management package, there will be two features available in the thing marked as a gateway
images/confluence/download/attachments/1408857432/edge_install_linux_start2_v1.png

In case you have booked the Asset Communication package, there should be at least a second revision visible in the details view.

Check the connection state from the runtime side

To check for failures see the log file cloud.connector.generic/logs/log.txt

Further reading

Find the full Bosch IoT Edge documentation at https://docs.bosch-iot-suite.com/edge/index.html#109611.htm

Find the full Bosch IoT Edge Services documentation at https://docs.bosch-iot-suite.com/edge/edge-services/en/index.html#95520.htm