Microsoft Azure Sphere Device REST APIs enables users to interact with an Azure Sphere device using REST APIs. This is useful during manufacturing operations. This folder contains two different implementations one in C# and the other in Python. These packages are published by Microsoft into PyPI and NuGet so they can be easily incorporated into Python or C# scripts. They are also used by the manufacturing tools Python scripts.
| Folder | Description |
|---|---|
| CSharp | Contains NuGet package source code and samples for Microsoft Azure Sphere Device REST APIs for C#. |
| Python | Contains Python package source code and samples for Microsoft Azure Sphere Device REST APIs for Python. |
| Category | Description | C# Source File | Python Source File |
|---|---|---|---|
| App | Manage applications on the attached device. | App.cs | app.py |
| Capability | View device capability configurations. | Capabilities.cs | capabilities.py |
| Certificate | Manage certificates on the attached device. | Certificate.cs | certificate.py |
| Device | Manage Azure Sphere devices. | Device.cs | device.py |
| Devices | List Azure Sphere devices connected to the local PC. | Devices.cs | devices.py |
| Image | Manage device images. | Image.cs | image.py |
| Manufacturing | Manage the manufacturing state of attached devices. | Manufacturing.cs | manufacturing.py |
| Network | Manage network interfaces on the attached device. | Network.cs | network.py |
| Sideload | Deploy and manage applications on the attached device. | Sideload.cs | sideload.py |
| Wi-Fi | Manage Wi-Fi configurations for the attached device. | Wifi.cs | wifi.py |
| App API | Description | C# Function Name | Python Function Name |
|---|---|---|---|
| Get app quota | Get the storage quota and usage for an application on the attached device. | GetAppQuota | get_app_quota |
| Get application status | Get the status of an application on the attached device. | GetAppStatus | get_app_status |
| Get memory statistics | Get the memory statistics for an application on the attached device. | GetMemoryStatistics | get_memory_statistics |
| Set application status | Set the application status of an application on the attached device. | SetAppStatus | set_app_status |
This function makes a GET request to https://192.168.35.2/app/quota/{componentID}, to show the storage quota and usage of the application on the attached device. {componentID} is the ID of the component to get the quota information for.
The Azure Sphere CLI command that calls this API is azsphere device app show-quota.
The following JSON is the example response for a successful HTTP/GET request.
{"UsageKB":0,"LimitKB":0}This function makes a REST GET call to https://192.168.35.2/app/status/{componentID}, to show the status of the application on the attached device. {componentID} is the ID of the component to show the status of.
The Azure Sphere CLI command that calls this API is azsphere device app show-status.
The following JSON is the example response for a successful HTTP/GET request.
{"state":"running"}This function makes a REST GET call to https://192.168.35.2/stats/memory/groups/applications, to show the memory statistics for applications on the attached device.
The Azure Sphere CLI command that calls this API is azsphere device app show-memory-stats.
The following JSON is the example response for a successful HTTP/GET request.
{
"memoryStats": {
"currentMemoryUsageInBytes": 147456,
"peakUserModeMemoryUsageInBytes": 98304,
"userModeMemoryUsageInBytes": 98304
}
}This function makes a REST PATCH call to https://192.168.35.2/app/status/{componentID}, to set the status of the application on the attached device. {componentID} is the ID of the component to set the status of.
The three states for the trigger parameter are start, stop, and startDebug.
The Azure Sphere CLI commands that call this API are azsphere device app start and azsphere device app stop.
The following JSON is the example response for a successful HTTP/SET request.
{"state":"stopped"}| Certificate API | Description | C# Function Name | Python Function Name |
|---|---|---|---|
| Add certificate | Add a certificate to the attached device's certificate store. | AddCertificate | add_certificate |
| Get all certificates | Get all certificate IDs in the attached device's certificate store. | GetAllCertificates | get_all_certificates |
| Get certificate | Get details of a certificate in the attached device's certificate store. | GetCertificate | get_certificate |
| Get certificate space | Get the available free space in the attached device's certificate store. | GetCertificateSpace | get_certificate_space |
| Remove certificate | Delete a certificate in the attached device's certificate store. | RemoveCertificate | remove_certificate |
This function makes a REST POST call to https://192.168.35.2/certstore/certs/{identifier}, to add a certificate to the attached device's certificate store. Here {identifier} is the ID of the certificate for which to add.
The Azure Sphere CLI command that calls this API is azsphere device certificate add.
The following JSON is the example response for a successful HTTP/POST request.
{}Thi function makes a REST GET call to https://192.168.35.2/certstore/certs, to list certificates in the attached device's certificate store.
The Azure Sphere CLI command that calls this API is azsphere device certificate list.
The following JSON is the example response for a successful HTTP/GET request.
{"identifiers":["TestCert1","TestCert2"]}This function makes a REST GET call to https://192.168.35.2/certstore/certs/{identifier}, to show details of a certificate in the attached device's certificate store. Here {identifier} is the ID of the certificate for which to show the details.
The Azure Sphere CLI command that calls this API is azsphere device certificate show.
The following JSON is the example response for a successful HTTP/GET request.
{
"id": "testCA",
"notBefore": "2022-04-12T08:31:54",
"notAfter": "2023-04-12T08:51:54",
"subjectName": "/CN=<TempRootCertificate>",
"issuerName": "/CN=<TempRootCertificate>"
}This function makes a REST GET call to https://192.168.35.2/certstore/space, to show the available free space in the attached device's certificate store.
The Azure Sphere CLI command that calls this API is azsphere device certificate show-quota.
The following JSON is the example response for a successful HTTP/GET request, the result is in bytes.
{"AvailableSpace":"24514"}This function makes a REST DELETE call to https://192.168.35.2/certstore/certs/{identifier}, to delete a certificate in the attached device's certificate store. Here {identifier} is the ID of the certificate for which to delete.
The Azure Sphere CLI command that calls this API is azsphere device certificate delete.
The following JSON is the example response for the HTTP/DELETE request.
{}| Capabilities API | Description | C# Function Name | Python Function Name |
|---|---|---|---|
| Get device capabilities | Get the current device capability configuration of the attached device. | GetDeviceCapabilities | get_device_capabilities |
This function makes a REST GET call to https://192.168.35.2/device/capabilities, to get the current device capability configuration of the attached device.
A device can have the following capabilities:
appDevelopmentwith a value of11enableRFTestModewith a value of12fieldServicingwith a value of13
The Azure Sphere CLI command that calls this API is azsphere device capability show-attached.
The following JSON is the example response for a successful HTTP/GET request:
{"device_capabilities":[11]}| Device API | Description | C# Function Name | Python Function Name |
|---|---|---|---|
| Clear error report data | Clear error report data. | ClearErrorReportData | clear_error_report_data |
| Get device REST API version | Get the version of REST API. | GetDeviceRestAPIVersion | get_device_rest_api_version |
| Get device OS version | Get the version of the OS. | GetDeviceOSVersion | get_device_os_version |
| Get device security state | Get the device security state. | GetDeviceSecurityState | get_device_security_state |
| Get device status | Get the device status. | GetDeviceStatus | get_device_status |
| Get diagnostic log | Get the diagnostics log. | GetDiagnosticLog | get_diagnostic_log |
| Get error report data | Get the device error report. | GetErrorReportData | get_error_report_data |
| Restart device | Restart the attached device. | RestartDevice | restart_device |
This function makes a DELETE request to https://192.168.35.2/telemetry, to clear error report data.
The Azure Sphere CLI command that calls this API is azsphere get-support-data.
{}
This function makes a GET request to https://192.168.35.2/status, to get REST API version on the attached device. This request is made purely to get the HTTP Header that contains the REST API version information.
There is no Azure Sphere CLI command corresponding to this API call.
{"REST-API-Version":"4.4.0"}
This function makes a GET request to https://192.168.35.2/osversion, to get the operating system (OS) version on the attached device.
The Azure Sphere CLI command that uses this API is azsphere device show-os-version.
{"osversion":"22.11"}
This function makes a REST GET call to https://192.168.35.2/device/security_state, to get the security state on the attached device.
There is no Azure Sphere CLI command corresponding to this API call.
The following JSON is the example response for a successful HTTP/GET request for anonymous authentication type.
{
"securityState": "SECURE",
"deviceIdentifier": "352fe1f59e40ef8a9266415e81af32b5b07d8f2bbd6b5650cef4a70b86c7fcbc70b129a41fbc6d02f8bb4aaabc52cd5740c85427d205e46a166b7e41135eb968",
"deviceIdentityPublicKey": "352fe1f59e40ef8a9266415e81af32b5b07d8f2bbd6b5650cef4a70b86c7fcbc70b129a41fbc6d02f8bb4aaabc52cd5740c85427d205e46a166b7e41135eb968"
}This function makes a GET request to https://192.168.35.2/status, to get the status of the attached device.
The Azure Sphere CLI command that calls this API is azsphere device restart.
{ "uptime": 634 }
This function makes a REST GET call to https://192.168.35.2/log, to gather diagnostic data about your device configurations.
There are no public tools to decode this log, and you would need to send this log to Microsoft to decode the logs. Refer to Azure Sphere Support docs.
The Azure Sphere CLI command that calls this API is azsphere get-support-data.
The result of the HTTP/GET request is a byte array.
This function makes a GET request to https://192.168.35.2/telemetry, to retrieve error report data for the attached device.
The results of the HTTP/GET request is a byte array.
The Azure Sphere CLI command that calls this API is azsphere get-support-data.
This function makes a POST request with no body to https://192.168.35.2/restart to restart the attached device.
The Azure Sphere CLI command that calls this API is azsphere device restart
{ "restartingSystem": true }
| Devices API | Description | C# Function Name | Python Function Name |
|---|---|---|---|
| Get active device IP address | Get the active device IP address . | GetActiveDeviceIpAddress | get_active_device_ip_address |
| Get attached devices | Get the list of attached devices. | GetAttachedDevices | get_attached_devices |
| Set active device IP address | Set the device IP address that the REST APIs should use. | SetActiveDeviceIpAddress | set_active_device_ip_address |
This function gets the IP address of the device that the REST APIs use when multiple devices are attached. Note: Multiple devices can be connected on Windows only.
Windows: This function makes a REST GET call to http://localhost:48938/api/service/devices, to get the list the attached devices.
Linux: This function checks the network adapter status to determine whether there is an attached device.
The Azure Sphere CLI commands that calls this API are azsphere device list-attached and azsphere device show-attached.
The following JSON is the example response for a successful HTTP/GET request.
Windows:
[
{
"IpAddress": "192.168.35.2",
"DeviceConnectionPath": "1243"
}
]Linux:
[
{
"IpAddress": "192.168.35.2",
"DeviceConnectionPath": ""
}
]This function sets the IP address of the device to run the command on when multiple devices are attached. Multi-board is supported only on Windows.
| Image API | Description | C# Function Name | Python Function Name |
|---|---|---|---|
| Get all images | List the images currently on the attached device. | GetImages | get_images |
This function makes a REST GET call to https://192.168.35.2/images, to list the images currently on the attached device.
The Azure Sphere CLI command that calls this API is azsphere device image list-installed --full.
The following JSON is an example of a partial response for a successful HTTP/GET request:
{
"is_ota_update_in_progress": false,
"has_staged_updates": false,
"restart_required": false,
"components": [
{
"uid": "ec966946b-893b-4ff2-9ef1-b41725a8c652",
"image_type": 7,
"is_update_staged": false,
"does_image_type_require_restart": true,
"images": [
{
"uid": "3ba893921-535b-1684-b0a8-05ca4a30934a",
"length_in_bytes": 2544816,
"uncompressed_length_in_bytes": 2544816,
"replica_type": 0
}
],
"name": "NW Kernel"
}
]
}See the Image - Get Metadata for more information on the image type.
| Manufacturing API | Description | C# Function Name | Python Function Name |
|---|---|---|---|
| Get manufacturing state | Get the manufacturing state of the attached device. | GetManufacturingState | get_device_manufacturing_state |
| Set manufacturing state | Set the manufacturing state of the attached device. | SetDeviceManufacturingState | set_device_manufacturing_state |
This function makes a REST GET call to https://192.168.35.2/device/manufacturing_state, to show the manufacturing state of the attached device.
The Azure Sphere CLI command that calls this API is azsphere device manufacturing-state show.
The following JSON is the example response for a successful HTTP/GET request.
{"manufacturingState":"Module1Complete"}This function makes a REST PUT call to https://192.168.35.2/device/manufacturing_state, to update the manufacturing state of the attached device.
NOTE: Set the manufacturing state with caution. This action cannot be reversed.
There are four manufacturing states: Blank, Module1Complete, DeviceComplete, and Unknown. The default state that the device ships in is Blank. The two states that you can set with this command are Module1Complete and DeviceComplete.
The Azure Sphere CLI command that calls this API is azsphere device manufacturing-state update.
The following JSON is the example response for performing the HTTP/PUT request.
{}This function makes a REST POST call to https://192.168.35.2/net/proxy, to configure the network proxy on the attached device.
The Azure Sphere CLI command that calls this API is azsphere device network proxy apply.
The following JSON is the example response for a successful HTTP/POST request for anonymous authentication:
{
"address": "192.168.98.3",
"enabled": true,
"port": 123,
"authenticationType": "anonymous",
"noProxyAddresses": []
}See the proxy code snippets, to learn more about interacting with a proxy on an Azure Sphere device.
This function makes a REST DELETE call to https://192.168.35.2/net/proxy, to delete the proxy connection on the attached device.
The Azure Sphere CLI command that calls this API is azsphere device network proxy delete.
An example for a successful HTTP/DELETE request is as below.
{}This function makes a REST GET call to https://192.168.35.2/wifi/diagnostics/networks, to get logs of all failed network connection attempts.
The Azure Sphere CLI command that calls this API is azsphere get-support-data.
The following JSON is the example response for a successful HTTP/GET request.
{
"values": [
{
"timestamp": "2000-01-01t00:04:37+0000",
"networkId": 0,
"ssid": "ExampleNetworkName",
"error": "NetworkNotFound",
"configState": "disabled",
"connectionState": "disconnected"
}
]
}This function makes a REST GET call to https://192.168.35.2/net/interfaces, to list the network interfaces for the attached device.
The Azure Sphere CLI command that calls this API is azsphere device network list-interfaces.
An example for a successful HTTP/GET request is as below.
{
"interfaces": [
{
"interfaceName": "azspheresvc",
"interfaceUp": true,
"connectedToNetwork": false,
"ipAcquired": false,
"connectedToInternet": false,
"ipAddresses": [
"192.168.35.2"
]
},
{
"interfaceName": "lo",
"interfaceUp": true,
"connectedToNetwork": false,
"ipAcquired": false,
"connectedToInternet": false,
"ipAddresses": [
"127.0.0.1"
]
}
]
}This function makes a REST GET call to https://192.168.35.2/wifi/diagnostics/networks/{id}, to get the failed network connection attempts of a named network. {id} is the ID of the network for which you want get the logs.
The Azure Sphere CLI command that calls this API is azsphere get-support-data.
The following JSON is the example response for a successful HTTP/GET request.
{
"timestamp": "2000-01-01t00:04:37+0000",
"networkId": 0,
"ssid": "ExampleNetworkName",
"error": "NetworkNotFound",
"configState": "disabled",
"connectionState": "disconnected"
}This function makes a REST GET call to http://192.168.35.2/net/firewall/rulesets, to list firewall rules for the attached device.
The Azure Sphere CLI command that calls this API is azsphere device network list-firewall-rules.
An example for a successful HTTP/GET request is as below.
{
"rulesets": [
{
"hook": "PREROUTING",
"isValid": false,
"rules": []
},
{
"hook": "INPUT",
"isValid": true,
"rules": [
{
"sourceIP": "0.0.0.0",
"sourceMask": "0.0.0.0",
"destinationIP": "127.0.0.1",
"destinationMask": "255.255.255.255",
"uid": 4292567295,
"action": "accept",
"interfaceInName": "",
"interfaceOutName": "",
"state": "none",
"tcpMask": [],
"tcpCmp": [],
"tcpInv": false,
"protocol": "any",
"sourcePortRange": {
"min": 0,
"max": 65535
},
"destinationPortRange": {
"min": 0,
"max": 65535
},
"packets": 3,
"bytes": 249
}
]
}
]
}This function makes a REST GET call to https://192.168.35.2/net/interfaces/{networkInterfaceName}, to get the status of network interfaces. {networkInterfaceName} is the name of the network interface for which to get the status.
There is no Azure Sphere CLI command associated with this API call.
The following JSON is the example response for a successful HTTP/GET request for an interface with name wlan0.
{
"interfaceName": "wlan0",
"interfaceUp": true,
"connectedToNetwork": true,
"ipAcquired": true,
"connectedToInternet": true,
"hardwareAddress": "1d:d8:47:fe:f7:33",
"ipAssignment": "dynamic",
"ipAddresses": [
"172.20.10.3"
]
}This function makes a REST GET call to https://192.168.35.2/net/proxy, to get the proxy connection on the attached device.
The Azure Sphere CLI command that calls this API is azsphere device network proxy show.
The following JSON is the example response for a successful HTTP/GET request.
{
"address": "192.168.98.3",
"enabled": true,
"port": 123,
"authenticationType": "anonymous",
"noProxyAddresses": []
}This function makes a REST GET call to https://192.168.35.2/net/status, to get the network status of the device.
The Azure Sphere CLI command that calls this API is azsphere device network show-status.
The following JSON is the example response for a successful HTTP/GET request.
{
"deviceAuthenticationIsReady": true,
"networkTimeSync": "complete",
"proxy": "disabled"
}This function makes a REST PATCH call to https://192.168.35.2/net/interfaces/{networkInterfaceName}, to update the network interface configuration for the attached device. {networkInterfaceName} is the name of the interface that is to be updated.
The list of current network interface names can be obtained by calling the Get all network interfaces function.
The Azure Sphere CLI command that calls this API is azsphere device network update-interface.
NOTE: This command can only be executed on an ethernet adapter, not on Wi-Fi.
The following JSON is the example response for a successful HTTP/PATCH request.
{}| Sideload API | Description | C# Function Name | Python Function Name |
|---|---|---|---|
| Delete image | Delete an image on the device. | DeleteImage | delete_image |
| Install images | Install all staged images on the device. | InstallImages | install_images |
| Stage image | Stage an image on the device. | StageImage | stage_image |
This function makes a REST DELETE call to https://192.168.35.2/app/image/{componentID}, to delete an image from a device. {componentID} is the component ID of the component (application) on your device.
The Azure Sphere CLI command that calls this API is azsphere device app delete.
The following JSON is the example response for a successful HTTP/DELETE request.
{}This function makes a REST POST call to https://192.168.35.2/update/install, to install an image on the attached device.
An application can be installed with an appControlMode of either Auto or Manual. Auto starts the application automatically after installation while Manual requires a manual restart.
You need to first stage the image, before installing. See Stage image
The Azure Sphere CLI command this API calls is azsphere device sideload deploy.
The following JSON is the example response for a successful HTTP/POST request.
{}This function makes a REST PUT call to https://192.168.35.2/update/stage, to stage image on the attached devices. The content of the image package is sent as the body in the REST call.
The Azure Sphere CLI command that calls this API is azsphere device sideload deploy.
The following JSON is the example response for a successful HTTP/PUT request.
{}This functionmakes a REST GET call to https://192.168.35.2/wifi/config/networks, to add a Wi-Fi network on the attached device.
The CLI command this API calls is azsphere device wifi add.
{
"ssid": "ExampleNetworkName",
"configState": "enabled",
"connectionState": "unknown",
"id": 0,
"securityState": "psk",
"targetedScan": false
}This function makes a REST PATCH call to https://192.168.35.2/wifi/config/networks/{id}, to modify a Wi-Fi network configuration. {id} is the ID of the Wi-Fi network configuration you would like to modify.
configState can take one of four values: unknown, enabled, disabled, temp-disabled.
There is no Azure Sphere CLI command associated with this API call.
The following JSON is the example response for a successful HTTP/PATCH request.
{
"ssid": "ExampleNetworkName",
"configState": "disabled",
"connectionState": "disconnected",
"id": 0,
"securityState": "psk",
"targetedScan": false
}This function makes a REST PATCH request to https://192.168.35.2/wifi/interface, to change the Wi-Fi interface state on the attached device.
Note: The state might take a while to change, and hence you might need to poll to see the state change.
The Azure Sphere CLI commands this API calls are azsphere device wifi enable and azsphere device wifi disable.
The following JSON is the example response for a successful HTTP/PATCH request.
{}This function makes a REST GET call to https://192.168.35.2/wifi/config/networks, to list the current Wi-Fi configurations for the attached device.
The Azure Sphere CLI command this API calls is azsphere device wifi list.
The following JSON is the example response for a successful HTTP/GET request.
{
"values": [
{
"ssid": "ExampleNetworkName",
"configState": "enabled",
"connectionState": "disconnected",
"id": 0,
"securityState": "psk",
"targetedScan": false
}
]
}This function makes a REST GET call to https://192.168.35.2/wifi/config/networks/{id}, to get details of a Wi-Fi network on the attached device. {id} is the ID of the network to show details for.
The Azure Sphere CLI command this API calls is azsphere device wifi show.
The following JSON is the example response for a successful HTTP/GET request.
{
"ssid": "ExampleNetworkName",
"configState": "enabled",
"connectionState": "disconnected",
"id": 0,
"securityState": "psk",
"targetedScan": false
}This function makes a REST GET request to https://192.168.35.2/wifi/interface, to get the status of the wireless interface on the attached device.
The Azure Sphere CLI command this API calls is azsphere device wifi show-status.
The following JSON is the example response for a successful HTTP/GET request.
{
"ssid": "ExampleNetworkName",
"configState": "enabled",
"connectionState": "connected",
"securityState": "psk",
"mode": "station",
"key_mgmt": "WPA2-PSK",
"wpa_state": "COMPLETED",
"address": "1c:f1:f1:11:91:a1",
"freq": 5220,
"ip_address": "902.21.11.1",
"id": 0
}This function makes a REST GET request to https://192.168.35.2/wifi/scan, to scan for available Wi-Fi networks visible to the attached device.
The Azure Sphere CLI command this API calls is azsphere device wifi scan.
The following JSON is the example response for a successful HTTP/GET request.
{
"values": [
{
"bssid": "11:11:11:11:11:12",
"freq": 5220,
"signal_level": -40,
"ssid": "ExampleNetworkName",
"securityState": "psk"
},
{
"bssid": "11:11:11:11:11:11",
"freq": 5220,
"signal_level": -61,
"ssid": "I-WPA",
"securityState": "eaptls"
},
{
"bssid": "11:11:11:11:11:21",
"freq": 5220,
"signal_level": -60,
"ssid": "\u0000",
"securityState": "psk"
}
]
}This function makes a REST DELETE call to https://192.168.35.2/wifi/config/networks/{id}, to forget a Wi-Fi network on the attached device. {id} is ID of the network to forget.
The Azure Sphere CLI command this API calls is azsphere device wifi forget.
The following JSON is the example response for a successful HTTP/DELETE request.
{}