Quickstart: Configure networking and update the device OS
Important
This is the Azure Sphere (Legacy) documentation. Azure Sphere (Legacy) is retiring on 27 September 2027, and users must migrate to Azure Sphere (Integrated) by this time. Use the Version selector located above the TOC to view the Azure Sphere (Integrated) documentation.
After you claim your Azure Sphere device, configure it for networking so that it can receive cloud updates from the Azure Sphere Security Service and communicate with services such as an Azure IoT Hub. When you've configured and enabled networking, your device can receive an OS update from the cloud.
Important
This topic describes how to connect your Azure Sphere device to a Wi-Fi network. If your device supports a different networking mechanism and does not support Wi-Fi, connect it to the internet using that mechanism and proceed to Receive device update.
Prerequisites
- Install Visual Studio Code for Windows or for Linux.
- Install the SDK for Windows or for Linux
- Quickstart: Choose a tenant and claim your device
Set up Wi-Fi on your Azure Sphere device
Follow these steps to configure Wi-Fi on your Azure Sphere device:
Connect your Azure Sphere device to your computer.
Open a command-line interface using PowerShell, Windows Command Prompt, or Linux command shell.
Register the device's MAC address if your network environment requires it. Use the following command to get the MAC address, and then register it according to the procedure for your environment:
azsphere device wifi show-statusAdd your Wi-Fi network to the device by using the azsphere device wifi add command as follows:
azsphere device wifi add --ssid <SSID> --psk <EXAMPLEPSK>Replace <SSID> with the name of your network. Network SSIDs are case-sensitive. If the SSID is hidden, add
--targeted-scanto try to connect to it anyway. You can use azsphere device wifi scan to get a list of available Wi-Fi networks.Replace <EXAMPLEPSK> with your WPA/WPA2 key. Azure Sphere devices do not support WEP. To add an open network, omit
--psk.If the network SSID or key has embedded spaces or an ampersand, enclose the SSID or key in single quotes. If the SSID or key includes a quotation mark, use a backslash to escape the quotation mark. Backslashes do not have to be escaped if they are part of a value. For more information, see Quotation marks and escapes characters. For example:
azsphere device wifi add --ssid "New SSID" --psk "key \'value\' with quotes"It typically takes several seconds for networking to be ready on the board, but might take longer, depending on your network environment.
Use the azsphere device wifi show-status command to check the status of the connection:
azsphere device wifi show-statusDuring update, the azsphere device wifi show-status command may temporarily show an unknown configuration state. The following example shows successful results for a secure WPA2 connection:
----- ------------------ --------------- ------------- --------- ------- ------------- --------- ------------- ----------------- SSID ConfigurationState ConnectionState SecurityState Frequency Mode KeyManagement WpaState IpAddress MacAddress =============================================================================================================================== <value> enabled connected psk 2412 station WPA2-PSK COMPLETED <value> <value> ----- ------------------ --------------- ------------- --------- ------- ------------- --------- ------------- -----------------
The azsphere device wifi command supports several additional options. Type azsphere device wifi for a complete list, or azsphere device wifi option --help for help on an individual option.
Follow these steps to configure Wi-Fi on your Azure Sphere device:
Connect your Azure Sphere device to your computer.
Expand the Device node for the device you are interested in.
Expand the Wi-Fi node. You should see something like the following:
Expand the node labeled Disconnected and you should see the MAC address of the device. Register the device's MAC address if your network environment requires it. Note the refresh button at the right; you will need this to view the connectivity information after you have connected to a network.
Expand the Available networks node, if possible. Hover over the network you wish to connect to and select Connect (this appears as a + at the right of the node). If the network requires a Pre-Shared Key (psk), type the network password in the textbox that appears and press Enter.
Return to the node previously labeled Disconnected, which should now read Connected to: <network>. If you still see Disconnected after a few moments, click the refresh button on this node to view the updated connection status of your device.
You should see the following information:
- SSID
- Configuration state
- Connection state
- Security state
- Frequency
- Mode
- Key management type
- WPA state
- IP address
- MAC address
This is the same information as reported by the CLI command azsphere device wifi show-status.
You should also see the network you've connected to appear on your Saved networks node.
Follow these steps to configure Wi-Fi on your Azure Sphere device:
Connect your Azure Sphere device to your computer.
Expand the Device node for the device you are interested in.
Expand the Wi-Fi node. You should see something like the following:
Expand the node labeled Disconnected and you should see the MAC address of the device. Register the device's MAC address if your network environment requires it. Note the refresh button at the right; you will need this to view the connectivity information after you have connected to a network.
Expand the available networks node, if possible. Right-click the network you wish to connect to and select Connect. If your network requires a Pre-Shared Key (PSK), type the network password in the PSK textbox and press Enter.
Return to the node previously labeled Disconnected, which should now read Connected to: <network>. If you still see Disconnected after a few moments, click the refresh button on this node to view the updated connection status of your device.
You should see the following information:
- IP address
- Security state
- MAC address
- WPA state
- Mode
- Frequency
- Key management type
- Whether a targeted scan was used
This is the same information as reported by the CLI command azsphere device wifi show-status.
You should also see the network you've connected to appear on your Saved networks node.
Enable or disable Wi-Fi networks
You can enable a configured Wi-Fi network using the azsphere device wifi enable command:
azsphere device wifi enable --id <ID>
Replace <ID> with the ID of the network, which can be obtained by calling azsphere device wifi list.
You can disable a configured Wi-Fi network using the azsphere device wifi disable command as follows:
azsphere device wifi disable --id <ID>
Replace <ID> with the ID of the network, which can be obtained by calling azsphere device wifi list.
To enable a configured Wi-Fi network in Visual Studio Code's Azure Sphere Explorer:
Expand the Saved networks node.
Find a disabled network; these will have a Wi-Fi symbol to the right of their names.
Select the Wi-Fi symbol, or right-click the network name and then select Enable.
To disable a configured Wi-Fi network in Visual Studio Code's Azure Sphere Explorer:
Expand the Saved networks node.
Find an enabled network; these will have a Wi-Fi symbol with a backslash through it to the right of their names.
Select the disabled Wi-Fi symbol, or right-click the network name and then select Disable.
To enable a configured Wi-Fi network in Visual Studio's Azure Sphere Explorer:
Expand the Saved networks node.
Find a disabled network; these will have a connection symbol to the right of their names.
Select the connection symbol, or right-click the network name and then select Enable.
To disable a configured Wi-Fi network in Visual Studio Code's Azure Sphere Explorer:
Expand the Saved networks node.
Find an enabled network; these will have a disconnect symbol to the right of their names.
Select the disconnect symbol, or right-click the network name and then select Disable.
Forget a Wi-Fi network
You can forget a configured Wi-Fi network using the azsphere device wifi forget command:
azsphere device wifi forget --id <ID>
Replace <ID> with the ID of the network, which can be obtained by calling azsphere device wifi list.
To forget a configured Wi-Fi network in Visual Studio Code's Azure Sphere Explorer:
- Expand the Saved networks node.
- Right-click the network you want to forget and then select Forget.
To forget a configured Wi-Fi network in Visual Studio's Azure Sphere Explorer:
- Expand the Saved networks node.
- Right-click the network you want to forget and then select Forget.
Receive device update
The Azure Sphere device checks for Azure Sphere OS and application updates each time it boots, when it initially connects to the internet, and at 24-hour intervals thereafter. If updates are available, download and installation could take as much as 15-20 minutes and might cause the device to restart.
To check on update status, type the following command:
azsphere device show-deployment-status
If you have an older Seeed MT3620 Development Kit, you may have to update it manually, as described in Update the OS on an early dev kit.
If you encounter Wi-Fi problems, first ensure that your Wi-Fi network uses 802.11b/g/n; Azure Sphere devices do not support 802.11a.
Note
Azure Sphere OS update is a staged process over a period that may be less than 15 minutes but can be longer depending on the internet connectivity. Between stages, the board will appear functional while the next group of updates is downloaded, but during the update you should expect the board to be unresponsive for several minutes at a time.