Set up an Azure IoT Edge device with symmetric key authentication

A free or standard IoT hub in your Azure subscription.

In your IoT Hub in the Azure portal, IoT Edge devices are created and managed separately from IOT devices that are not edge enabled.

1. Sign in to the Azure portal and navigate to your IoT hub.

2. In the left pane, select IoT Edge from the menu, then select Add an IoT Edge device.

   

3. On the Create a device page, provide the following information:

   • Create a descriptive device ID.
   • Select Symmetric key as the authentication type.
   • Use the default settings to auto-generate authentication keys and connect the new device to your hub.

4. Select Save.

All the edge-enabled devices that connect to your IoT hub are listed on the IoT Edge page.

When you're ready to set up your device, you need the connection string that links your physical device with its identity in the IoT hub.

1. From the IoT Edge page in the portal, click on the device ID from the list of IoT Edge devices.
2. Copy the value of either Primary Connection String or Secondary Connection String.

• A free or standard IoT hub in your Azure subscription
• Visual Studio Code
• Azure IoT Tools for Visual Studio Code

You can use the Azure IoT extensions for Visual Studio Code to perform operations with your IoT Hub. For these operations to work, you need to sign in to your Azure account and select your IoT Hub.

1. In Visual Studio Code, open the Explorer view.

2. At the bottom of the Explorer, expand the Azure IoT Hub section.

   

3. Click on the ... in the Azure IoT Hub section header. If you don't see the ellipsis, click on or hover over the header.

4. Choose Select IoT Hub.

5. If you aren't signed in to your Azure account, follow the prompts to do so.

6. Select your Azure subscription.

7. Select your IoT hub.

1. In the VS Code Explorer, expand the Azure IoT Hub Devices section.
2. Click on the ... in the Azure IoT Hub Devices section header. If you don't see the ellipsis, click on or hover over the header.
3. Select Create IoT Edge Device.
4. In the text box that opens, give your device an ID.

In the output screen, you see the result of the command. The device info is printed, which includes the deviceId that you provided and the connectionString that you can use to connect your physical device to your IoT hub.

All the devices that connect to your IoT hub are listed in the Azure IoT Hub section of the Visual Studio Code Explorer. IoT Edge devices are distinguishable from non-Edge devices with a different icon, and the fact that the $edgeAgent and $edgeHub modules are deployed to each IoT Edge device.

When you're ready to set up your device, you need the connection string that links your physical device with its identity in the IoT hub.

1. Right-click on the ID of your device in the Azure IoT Hub section.

2. Select Copy Device Connection String.

   The connection string is copied to your clipboard.

You can also select Get Device Info from the right-click menu to see all the device info, including the connection string, in the output window.

• An IoT hub in your Azure subscription.
• Azure CLI in your environment. At a minimum, your Azure CLI version must be 2.0.70 or newer. Use az --version to validate. This version supports az extension commands and introduces the Knack command framework.
• The IoT extension for Azure CLI.

Use the az iot hub device-identity create command to create a new device identity in your IoT hub. For example:

az iot hub device-identity create --device-id [device id] --hub-name [hub name] --edge-enabled

This command includes three parameters:

• --device-id or -d: Provide a descriptive name that's unique to your IoT hub.

• hub-name or -n: Provide the name of your IoT hub.

• --edge-enabled or --ee: Declare that the device is an IoT Edge device.

  

Use the az iot hub device-identity list command to view all devices in your IoT hub. For example:

az iot hub device-identity list --hub-name [hub name]

Any device that is registered as an IoT Edge device will have the property capabilities.iotEdge set to true.

When you're ready to set up your device, you need the connection string that links your physical device with its identity in the IoT hub. Use the az iot hub device-identity show-connection-string command to return the connection string for a single device:

az iot hub device-identity show-connection-string --device-id [device id] --hub-name [hub name]

The value for the device-id parameter is case-sensitive. Don't copy the quotation marks around the connection string.

On the IoT Edge device, open the configuration file.

sudo nano /etc/iotedge/config.yaml

Find the provisioning configurations of the file and uncomment the Manual provisioning configuration using a connection string section.

Update the value of device_connection_string with the connection string from your IoT Edge device. Make sure any other provisioning sections are commented out. Make sure the provisioning: line has no preceding whitespace and that nested items are indented by two spaces.

# Manual provisioning configuration using a connection string
provisioning:
  source: "manual"
  device_connection_string: "<ADD DEVICE CONNECTION STRING HERE>"
  dynamic_reprovisioning: false

To paste clipboard contents into Nano Shift+Right Click or press Shift+Insert.

Save and close the file.

CTRL + X, Y, Enter

After entering the provisioning information in the configuration file, restart the daemon:

sudo systemctl restart iotedge

1. On the IoT Edge device, run PowerShell as an administrator.

2. Use the Initialize-IoTEdge command to configure the IoT Edge runtime on your machine. The command defaults to manual provisioning with Windows containers.

   . {Invoke-WebRequest -useb https://aka.ms/iotedge-win} | Invoke-Expression; `
   Initialize-IoTEdge -ManualConnectionString -ContainerOs Windows
   

   • If you are using Linux containers, add the -ContainerOs parameter to the flag. Be consistent with the container option you chose with the Deploy-IoTEdge command that you ran previously.

     . {Invoke-WebRequest -useb https://aka.ms/iotedge-win} | Invoke-Expression; `
     Initialize-IoTEdge -ContainerOs Linux
     

   • If you downloaded the IoTEdgeSecurityDaemon.ps1 script onto your device for offline or specific version installation, be sure to reference the local copy of the script.

     . <path>/IoTEdgeSecurityDaemon.ps1
     Initialize-IoTEdge -ManualX509
     

3. When prompted, provide the device connection string that you retrieved in the previous section. The device connection string associates the physical device with a device ID in IoT Hub and provides authentication information.

   The device connection string takes the following format, and should not include quotation marks: HostName={IoT hub name}.azure-devices.net;DeviceId={device name};SharedAccessKey={key}

When you provision a device manually, you can use additional parameters to modify the process including:

• Direct traffic to go through a proxy server
• Declare a specific edgeAgent container image, and provide credentials if it's in a private registry

systemctl status iotedge

Get-Service iotedge

journalctl -u iotedge --no-pager --no-full

If you just finished installing the IoT Edge runtime, you may see a list of errors from the time between running Deploy-IoTEdge and Initialize-IoTEdge. These errors are expected, as the service is trying to start before being configured.

. {Invoke-WebRequest -useb https://aka.ms/iotedge-win} | Invoke-Expression; Get-IoTEdgeLog

On Linux devices, you need elevated privileges to run iotedge commands. After installing the runtime, sign out of your machine and sign back in to update your permissions automatically. Until then, use sudo to run commands with elevated privileges.

On Windows devices running Windows containers, the Moby container engine was installed as part of IoT Edge. The Moby engine was designed to run in parallel with Docker Desktop. You can use docker commands if you want to interact directly with the containers on your device. However, you must specifically target the Moby engine in case Docker Desktop is also installed on the device.

For example, to list all Docker images, use the following command:

docker images

To list all Moby images, modify the same command with a pointer to the Moby engine:

docker -H npipe:////./pipe/iotedge_moby_engine images

The engine URI is listed in the output of the installation script, or you can find it in the container runtime settings section for the config.yaml file.