Skip to content

iot-edge-register-device-symmetric.md

Latest commit

 

History

History
131 lines (81 loc) · 8.13 KB

iot-edge-register-device-symmetric.md

File metadata and controls

131 lines (81 loc) · 8.13 KB
ms.topic include
ms.date 02/19/2026
author sethmanheim
ms.author sethm
ms.service azure-iot-edge
services iot-edge
ms.custom sfi-ropc-nochange

Register your device

You can use the Azure portal, Visual Studio Code, or Azure CLI to register your device, depending on your preference.

Portal

In your IoT hub in the Azure portal, you create and manage IoT Edge devices separately from IoT devices that aren't edge enabled.

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

  2. In the left pane, select Devices from the menu, and then select Add Device.

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

    • Create a descriptive Device ID, such as my-edge-device-1 (all lowercase). Copy this Device ID, as you use it later.
    • Select the IoT Edge Device checkbox.
    • Select Symmetric key as the authentication type.
    • Use the default settings to autogenerate authentication keys, which connect the new device to your hub.

  4. Select Save.

You should see your new device listed in your IoT hub.

Visual Studio Code

Sign in to Azure

Use the Azure IoT extensions for Visual Studio Code to perform operations with your IoT hub. Make sure you install the Azure IoT extension prerequisites.

After you install the Azure IoT Edge and Azure IoT Hub extensions, you see an Azure icon in the left icon menu. Sign in to your Azure account through Visual Studio Code by selecting the Azure icon and then selecting Sign in to Azure.

Register a new device with Visual Studio Code

Registering a new device is similar to creating an IoT Edge device in the Azure portal. This virtual device is one of the twins, whereas the real world device is the other twin. Visual Studio Code can set up this virtual device for you through the following steps:

  1. In the Visual Studio Code Explorer menu, expand the Azure IoT Hub section.
  2. Select the ... ellipsis in the Azure IoT Hub section header. If you don't see the ellipsis, select or hover over the header.
  3. Select Create IoT Edge Device.
  4. In the text box that opens, give your device an ID, such as my-edge-device-1 (all lowercase), and press Enter.

In the output console of Visual Studio Code, you see the result of the command: a JSON printout. The device information includes the deviceId that you provided and generates a connectionString value that you can use to connect your physical device to your IoT hub. The output console also shows your keys and other device identifying information.

You can now see your device listed under the Azure IoT Hub > Devices section of the Explorer menu.

Note

If your device isn't listed, you might need to choose your IoT hub from the link Select IoT Hub provided under Azure IoT Hub and then follow the prompts. The prompts ask you to choose your subscription first and then your IoT hub. This process lets Visual Studio Code know about your IoT hub (and all devices in it). Refresh Visual Studio Code and your device should show.

Azure CLI

Use the az iot hub device-identity create command to create a new device identity in your IoT hub. Replace device_id_here with your own new and unique device ID, such as my-edge-device-1 (all lowercase). Replace hub_name_here with your existing IoT hub.

This command includes three parameters:

  • --device-id or -d: Provide a descriptive name that's unique within 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.

    az iot hub device-identity create --device-id device_id_here --hub-name hub_name_here --edge-enabled

If your CLI says The command requires the extension azure-iot. Do you want to install it now?, type Y and press Enter to initiate the download and create your device.

Now that you have a device registered in IoT Hub, in the next step you can retrieve provisioning information used to complete the installation and provisioning of the IoT Edge runtime.

View registered devices and retrieve provisioning information

Devices that use symmetric key authentication need their connection strings to complete installation and provisioning of the IoT Edge runtime. The connection string is generated for your IoT Edge device when you create the device. For Visual Studio Code and Azure CLI, the connection string appears in the JSON output. If you use the Azure portal to create your device, you can find the connection string from the device itself. When you select your device in your IoT hub, it's listed as Primary connection string on the device page.

Portal

The edge-enabled devices that connect to your IoT hub are listed on the Devices page of your IoT hub. If you have multiple devices, you can filter the list by selecting the Iot Edge Devices type, then select Apply.

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. Devices that authenticate with symmetric keys have their connection strings available to copy in the portal. To find your connection string in the portal, perform the following steps:

  1. From the Devices page, select the IoT Edge device ID from the list.
  2. Copy the value of either Primary Connection String or Secondary Connection String. Either key works.

Visual Studio Code

The Azure IoT Hub section of the Visual Studio Code Explorer lists all the devices that connect to your IoT hub. IoT Edge devices have a different icon, so you can easily distinguish them from non-edge devices. You can see 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. Here's how to get your connection string from Visual Studio Code:

  1. Right-click the ID (name) 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 context menu to see all the device info, including the connection string, in the output window.

Azure CLI

To see all devices in your IoT hub, use the az iot hub device-identity list command. Replace hub_name_here with your own IoT hub name:

az iot hub device-identity list --hub-name hub_name_here

Any device that you register as an IoT Edge device has the property capabilities.iotEdge set to true. You can see a lot of other metadata as JSON output as well, including your device IDs.

When you're ready to set up your device, you need its connection string that links your physical device with its identity in the IoT hub. Use the following az iot hub device-identity connection-string show command to return the connection string for a single device. Replace [device_id] and [hub_name] with your own values. The value for the device-identity parameter is case-sensitive.

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

You should see JSON output in the console, similar to the following example:

{
  "connectionString": "HostName=[hub_name].azure-devices.net;DeviceId=[device_id];SharedAccessKey=[device_key]"
}

Tip

The connection-string show command was introduced in version 0.9.8 of the Azure IoT extension, replacing the deprecated show-connection-string command. If you get an error running this command, make sure your extension version is updated to 0.9.8 or later. For more information and the latest updates, see Microsoft Azure IoT extension for Azure CLI.

When you copy the connection string to use on a device, don't include the quotation marks around the connection string.