DH2i DxOdyssey 21.0 Software: IoT on Azure Quick Start Guide

Download the PDF

DxOdyssey and SQL Edge IoT Modules on Azure

This quick start guide describes how to set up and configure the DxOdyssey and SQL Edge IoT Modules on Azure to communicate with a local machine running DxOdyssey using tunnels. This document assumes that the sites do not have direct network access to each another. Using this guide, the user will configure DxOdyssey on a local machine, create an Azure IoT Edge device, deploy DxOdyssey and SQL Edge modules, and configure the DxOdyssey module to communicate with the local machine using tunnels.

Prerequisites

  • Access to the Azure Portal.
  • A local VM with DxOdyssey installed, activated, and an active One-Time PassKey. Please reference the Ubuntu or RHEL/CentOS Installation Quick Start Guides for installation instructions.

    NOTE: In the installation guide, save the OTPK that is generated for joining the second gateway, but skip the section titled “Setup Second Gateway and Join to Gateway Group”. Separate instructions for joining the DxOdyssey IoT gateway to the local VM are given below.

Create DxOdyssey and SQL Edge Modules on Azure

  1. Go to the Azure portal at https://portal.azure.com
  2. Log into the Azure account.
  3. Create an Azure IoT Edge Ubuntu VM, Resource Group, IoT Hub, and IoT Edge Device using Microsoft’s IoT Edge Quick Start Documentation.
  4. Set the connection string for the IoT Edge device in Cloud Shell. The name of the resource group, the hostname of the Azure VM, and the primary connection string for the IoT Edge Device are needed for this command. The primary connection string can be found under the properties of the IoT Edge Device on Azure.
    • az vm run-command invoke -g <resource_group> -n <vm_name> ‐‐command-id RunShellScript ‐‐script “/etc/iotedge/configedge.sh ‘{device_connection_string}'”
  5. Deploy a DxOdyssey IoT Module.
    1. Go to the Azure Marketplace and search for DxOdyssey for IoT.
    2. Select DxOdyssey for IoT, then select Create.
    3. Specify the Subscription, IoT Hub Name, and IoT Edge Device name, then select Create.
    4. Select the module being created to see the properties and select Environment Variables. The environment variables are used to specify the DxOdyssey IoT module’s configuration options.
      1. Set the DX_LICENSE variable with the DxOdyssey license key.
      2. Set the DX_OTPK variable with the One-Time PassKey generated using the instructions from the perquisites section.
      3. Set the DX_PASSKEY variable to the gateway group passkey to use for DxOdyssey Client UI access.
      4. Add a DX_HOSTNAME (e.g. dxoedge1) variable to set a hostname for the module. This allows the user to redeploy the module while having it also retain membership in the gateway group when it attempts to rejoin. It also allows the alias to be used for tunnel origins and destinations.
    5. Select Review + Create, then select Create.
  6. Deploy a SQL Edge IoT Module.
    1. Go to the Azure Marketplace and search for Azure SQL Edge.
    2. Select Azure SQL Edge, then select Create.
    3. Specify the Subscription, IoT Hub Name, and IoT Edge Device Name, then select Create.
    4. Select Review + Create, then select Create.
  7. Connect to the Azure IoT Edge Ubuntu VM using ssh azureuser@<public_ip>.
  8. Verify the modules are active by running sudo iotedge list and note the name of the SQL Edge Module. This name will be used later to create tunnel that connects to the SQL instance.

Add a Tunnel to the Gateway Group and Connect Using SSMS

DxOdyssey uses TCP tunnels to connect to connect gateways at remote locations. The following command example illustrates the creation of a tunnel name SQL-EDGE with an origin gateway at the on-premise location (dxo1) that accepts connection from any IP on the local network (0.0.0.0) on port 11433. The destination gateway is the DxOdyssey IoT Module in Azure (i.e. the DX_HOST value of dxoedge1) and a destination of the Azure SQL Edge container on Azure (AzureSQLEdge) using the default port of 1433.

  1. To create a tunnel, run the following command:

    Syntax

    dxcli add-tunnel <name> <enabled [true|false]> <destination_gateway> <destination_address:destination_port> <origin_gateway,origin_address:origin_port[,address_filter]>

    Parameters

    Name Description Required
    name The name of the tunnel. True
    enabled Enable tunnel (true or false). True
    destination_gateway The name of the destination gateway. True
    destination_address The IP address or name of the destination. True
    destination_port The port number for the destination. True
    origin_gateway The name of the gateway where the listener is active. True
    origin_address Set to 0.0.0.0 to allow all IP connections or 127.0.0.1 for local connections only. True
    origin_port The port number for the origin gateway. True
    address_filter The name of the address filter to add to the tunnel. False

    Example

    dxcli add-tunnel SQL-EDGE true dxoedge1 AzureSQLEdge:1433 dxo1,0.0.0.0:11433

  2. Launch SQL Server Management Studio (SSMS).
  3. Use the connection string <dxo1_ip_address>,11433 to connect to the SQL Edge Module on Azure.

References

Download the PDF