Release Notes 18.11, 18.11.1, and 18.11.2

The Azure Sphere 18.11 preview release includes the changes, new features, and known issues described in this article.

The 18.11 release features substantial changes to the Azure Sphere Security Service and cloud infrastructure. These security improvements will enable devices that have been offline for an extended period to reconnect. As a result of this change, updating the OS to the 18.11 release will involve connecting the device to a PC and manually installing the OS instead of receiving the software over the air (OTA). We expect to update by OTA for future releases.

About the 18.11.1 SDK release

The Azure Sphere 18.11.1 SDK release supplements the 18.11 release by adding support for Private Ethernet. If you have already updated your device and development environment to 18.11, you do not need to update the SDK to 18.11.1 unless you plan to use the private Ethernet support. To update to the 18.11.1 SDK, download it from Visual Studio Marketplace and run Azure_Sphere_SDK_Preview_for_Visual_Studio.exe from the download to install. The 18.11.1 SDK works with the 18.11 OS release; there is not an 18.11.1 OS release.

About the 18.11.2 OS release

The 18.11.2 update resolves a problem that prevented Azure Sphere devices from connecting to Wi-Fi in some cases. If you have already updated your device and development environment to 18.11, you will receive the 18.11.2 release OTA. It includes only the Azure Sphere OS; it does not include the SDK. If you have not updated to 18.11, follow the instructions in Install the 18.11 release; you will receive the 18.11.2 update OTA after 18.11 installation is complete.

To ensure that your Azure Sphere device receives the 18.11.2 update, connect the device to the internet. Delivery of the update should occur within 24 hours. To download the update immediately, press the Reset button on the development board. Installation of the updated OS should complete within 10 minutes.

To verify installation, run the following command to list all images on the device:

azsphere device image list-installed --full

Scroll through the image list and verify that the image ID for NW Kernel matches the following:

Installed images:
...
--> NW Kernel
   --> Image type:   System software image type 7
   --> Component ID: ec96028b-080b-4ff5-9ef1-b40264a8c652
   --> Image ID:     44ed692e-ce49-4425-9aa6-952b84ce7b32
 ...
Command completed successfully in 00:00:02.0395495.

Install the 18.11 release

All Azure Sphere devices are shipped from the manufacturer with the Azure Sphere OS installed. Normally, connecting the device to Wi-Fi triggers over-the-air (OTA) OS update if a more recent version is available. For the 18.11 release, you must instead manually update each device because of substantial changes to the Azure Sphere Security Service and cloud infrastructure. Manual update requires that you connect the Azure Sphere device to a PC and use the device recovery procedure to replace the system software.

If you have an Azure Sphere device that has never been used, complete all the procedures in Install Azure Sphere. When you complete these steps, your device will be ready for application development. You can ignore the procedures that are described in this section.

If your Azure Sphere device has already been claimed, follow the instructions in these release notes to recover your device and reconnect to Wi-Fi. If you previously configured OTA application deployment, you will also need to create new feeds and device groups. Existing TP4.2.1 application will continue to run on this release, but require changes if you rebuild, as described in Target API set and Beta APIs later in this document.

Update the Azure Sphere OS on a claimed device

If this Azure Sphere device has already been claimed, follow these steps to update the Azure Sphere OS:

1. Connect your Azure Sphere device to your PC over USB.

2. Open an Azure Sphere Developer Command Prompt and run the azsphere command to determine which version of the Azure Sphere SDK Preview for Visual Studio is installed. If the utility reports version 18.11.n.n, you have the current version and can proceed to the next step.

   If the utility reports version 2.0.n.n, you need to update the SDK before you can update the OS. To update the SDK, download it from Visual Studio Marketplace and run Azure_Sphere_SDK_Preview_for_Visual_Studio.exe from the download to install the SDK.

3. Assign your device to a device group that does not deliver over-the-air application updates. The simplest way is to list the available device groups and select the "System Software Only" group:

   azsphere device-group list
   

    Listing all device groups.
    --> [ID: cd037ae5-27ca-4a13-9e3b-2a9d87f9d7bd] 'System Software Only'
   Command completed successfully in 00:00:02.0129466.
   

   Move your device to the System Software Only group:

   azsphere device update-device-group -d cd037ae5-27ca-4a13-9e3b-2a9d87f9d7bd
   

4. Run the following command to manually update the Azure Sphere OS:

   azsphere device recover
   

   You should see output similar to this:

   Starting device recovery. Please note that this may take up to 10 minutes.
   Board found. Sending recovery bootloader.
   Erasing flash.
   Sending images.
   Sending image 1 of 16.
   Sending image 2 of 16.
   . . .
   Sending image 16 of 16.
   Finished writing images; rebooting board.
   Device ID: <GUID>
   Device recovered successfully.
   Command completed successfully in 00:02:37.3011134.
   

If update is successful, the azsphere device show-ota-status command should return output similar to this:

azsphere device show-ota-status -v
Your device is running Azure Sphere OS version 18.11.
The Azure Sphere Security Service is targeting this device with Azure Sphere OS version 18.11.
Your device has the expected version of the Azure Sphere OS: 18.11.
Command completed successfully in 00:00:03.2653689.

If azsphere device show-ota-status fails with the following message, the device is in a device group that performs OTA application updates and is therefore receiving the older OS feed on which the OTA application depends.

warn: Your device running Azure Sphere OS version 18.11 is being targeted with a deprecated version TP4.2.1. Go to aka.ms/AzureSphereUpgradeGuidance for further advice and support.

To solve this problem, assign the device to the System Software Only device group as described in Step 3 and then run the azsphere device recover command again.

After your device is successfully updated, set it up for either application development or for field use.

To enable application development

Devices that are set up for application development receive system software OTA but do not receive application software OTA.

1. To enable local application development and debugging, use the prep-debug command as follows:

   azsphere device prep-debug
   

   This command enables application development on the device and moves it to a System Software device group that uses the new 18.11 preview OS feed.

2. Configure Wi-Fi on the device. The device recovery procedure deletes the existing Wi-Fi configuration.

To enable field use

Devices that are set up for field use can receive both system software and application software OTA, if they are linked to a feed that delivers applications. If your device previously received application updates OTA, set it up for field use to continue receiving them.

1. To set up the device for field use, run the prep-field command in the following form:

   azsphere device prep-field --newdevicegroupname <new-group-name>
   

   Replace <new-group-name> with a unique name for a device group. A new device group is required because of changes to the dependent OS feed at this release.

2. Rebuild the application you want to deploy. Be sure to update the target API set as described here.

3. Link your device to a new application software feed, as follows:

   azsphere device link-feed --newfeedname <name-for-new-feed> --dependentfeedid <**replace with new feed id**> --imagepath <image-path>
   

   Supply a unique name for the new feed and replace <image-path> with the path to the newly rebuilt application image that you want the feed to deliver. A new application feed is required because of the changes to the OTA mechanism.

   Important

   Specify "Preview MT3620" with feed ID 3369f0e1-dedf-49ec-a602-2aa98669fd61 as the dependent feed. Do not use the obsolete "Preview MT3620 Feed" (feed ID edd33e66-9b68-44c8-9d23-eb60f2e5018b), and do not link the device to an existing application feed that depends on this feed.

4. Configure Wi-Fi on the device. The device recovery procedure deletes the existing Wi-Fi configuration.

Behavior of TP 4.2.1 devices and SDK after 18.11 release

If you continue to use both the TP 4.2.1 OS and the TP 4.2.1 SDK, expect the following behavior:

• Existing TP 4.2.1 devices will continue to operate. Existing sideloaded or OTA applications can continue to communicate with an existing IoT Hub until support for TP 4.2.1 terminates (currently scheduled for January 15, 2019).

• TP 4.2.1 devices will no longer receive OTA application updates or Azure Sphere OS updates. Attempts to deploy or update applications OTA have no effect.

If you install the 18.11 SDK but continue to use a device that has the TP 4.2.1 OS, you may encounter the following behavior:

• The 18.11 SDK displays a reminder message about updating the attached Azure Sphere device whenever it performs an operation on device that is running the TP 4.2.1 release.

New features and changes in this release

This release includes substantial investments in our security infrastructure, and it incorporates some of your feedback. The following sections describe new and changed features.

Target API set and Beta APIs

This release includes Beta APIsfor testing and development. Beta APIs are still in development and may change in or be removed from a later release.

To enable you to develop applications that use either the production APIs or the production and Beta APIs, this Azure Sphere release adds the Target API Set property to the Project Properties in Visual Studio. The Target API Set value 1 selects only production APIs; the value 1+Beta1811 selects both production and Beta APIs for the current release.

Attempts to rebuild existing TP 4.2.1 applications with the 18.11 Azure Sphere SDK Preview for Visual Studio will initially fail with the following error:

'Target API Set' project property is not set. Open the Project Properties and set this field using the dropdown menu. Ensure that the Configuration selected on that page includes the active build configuration (for example, Debug, Release, All Configurations).

To correct this error:

1. Open the Azure Sphere project in Visual Studio.

2. On the Project menu, select project-name Properties.

3. Ensure that the Configuration is set to either All Configurations or Active (configuration name).

4. Select Target API Set. On the dropdown menu, choose 1 to use production APIs or 1+Beta1811 to use production and Beta APIs.

   

5. Click OK.

You can then rebuild the project.

For additional information about Beta APIs and the target API set, see Beta features.

Strict prototype checking

The Visual Studio compiler settings now include strict prototype checking by default. As a result, the gcc compiler returns a warning for a function that uses empty parentheses () instead of (void) to indicate that it has no arguments.

To eliminate the warning in existing Azure Sphere applications, edit the function signature to add void. For example, change int foo() to int foo(void).

Wi-Fi setup using Bluetooth low-energy (BLE)

This release includes a reference solution that shows how you can use a mobile device to configure Wi-Fi on an Azure Sphere-based device. The BLE solution requires the Windows 10 Fall Creators Edition, which provides additional required Bluetooth support.

Real-time clock

A Beta API enables applications to set and use the internal clock and leverages support for using a coin-cell battery to ensure the RTC continues to keep time when power is lost.

Mutable storage

A Beta API provides access to a maximum of 64k for storage of persistent read/write data.

Private Ethernet

You can connect Azure Sphere to a private Ethernet network by using a Microchip Ethernet part over a serial peripheral interface (SPI). This functionality enables an application that runs on the A7 chip to communicate with devices on a private, 10-Mbps network via standard TCP or UDP networking in addition to communicating over the internet via Wi-Fi.

External MCU update

A reference solution shows how your application can update the firmware of additional connected MCUs.

Software update improvements

The Azure Sphere security service now seamlessly handles expired root certificates to ensure that devices that are intermittently connected or are disconnected for long periods of time can always connect to Azure Sphere and securely update.

Ping command

Although the ping command previously worked to contact the Azure Sphere device over a USB connection, this unsupported functionality has been removed. Use the azsphere device show-attached command to verify device connectivity.

Known issues

This section lists known issues in the current release.

Feed list command fails

After the 18.11 release, the azsphere feed list command from the TP 4.2.1 SDK fails with the following message:

azsphere feed list
Listing all feeds.
error: Invalid argument provided.
error: Command failed in 00:00:01.2002890.

The reason for this failure is the addition of a new feed type at the 18.11 release. To avoid this error, update your Azure Sphere device OS and SDK to the 18.11 release.

Non-ASCII characters in paths

The Azure Sphere tools do not support non-ASCII characters in paths.

Development language

The Azure Sphere SDK supports application development only in C.

Currently, the Visual Studio Integrated Development Environment (IDE) does not generate an error if you add a C++ source file to an Azure Sphere project. However, C++ development is not supported, and the resulting project will not build correctly.