New preview feeds for nanoFramework!

Until now nanoFramework has been using MyGet as its NuGet feed provider to host preview and test packages.

MyGet is a decent provider but only offers 100MB storage on their free trier. Actually they offer 2GB to OSS projects (which is great) and for which we’ve applied, but it turns out that setting up the account for the OSS offer is an absolute pain! After more than two weeks and dozens of emails exchanged with their support we’ve decided to just move.

We already run most of our infrastructure on Azure DevOps and support for public feeds in Azure Artifacts were recently announced at Microsoft Build 2019. This has support for NuGet packages and the offer includes 2GB of storage. Considering all this, we’ve decided to move everything there.

How does this impact you as a C# developer consuming NuGet packages? Not much! It’s only a matter of editing the NuGet package source in visual studio to point to the new feed and you’re done.

The URL for the new feed is:

https://pkgs.dev.azure.com/nanoframework/feed/_packaging/sandbox/nuget/v3/index.json

This impacts the VS extension preview versions too. We are now publishing those on the Open Vsix Gallery. Likewise, if you are eager to get the latest and greatest, and you’re already subscribed to the preview feed, you have to update the URL to:

http://vsixgallery.com/feed/author/nanoframework/

For a detailed description on how to setup all this in Visual Studio, please read the earlier blog post here.

Have fun with nanoFramework!

NuGet, assembly and native versions

nanoFramework C# class libraries are distributed as NuGet packages to be consumed by projects. This has been like this since day one. NuGet packages are practical, easy to distribute, easy to consume, easy to update.

But they had a …minor… problem. Actually, make that two… 😉

One was that the dependency between the managed assembly version and the corresponding version of the native end. The initial approach on this (inherited from .NETMF) was that the native version numbering had to follow the managed version. The main reason being that, at deployment time, there is the need to check if the device has support for what is about to be deployed to it. Nothing against this check that is perfectly reasonable. But – and this is a big but – this check is too strict. A detailed explanation on this has already been provided in this other blog post. Basically, what happened was this: even if the native code hadn’t any change whatsoever, it was forced to “change” just because the version had to bump in order to follow the managed one. This led to a consequence that is kind of severe in our context: forces to update the firmware on the target devices, which is something to be avoided at all costs!

This was improved a few weeks ago with the addition of the AssemblyNativeVersion attribute to our class libraries. This attribute is there to decouple the version numbers in the managed assembly and the native implementation. With it, the check on the required version on the target device at deployment time is possible and, by decoupling it from the managed version, made it possible to keep improving and changing the manged assembly as needed without forcing the native one to follow. Only when there is a real need to change the native part it’s version will have to be bumped

The second problem was that, because of that strict versioning dependency, whenever the version of an assembly changed all the dependent ones had to follow. The consequence is that this required massive and cascading updates that are time consuming and force everyone and everything to follow upon. If the version of mscorlib changed, guess what? All other class libs had to change along just to follow it!!

This too has been improved. Because of all the above, there is no need for this strict dependency anymore. The native versions have been bumped to a high number to make it clear to developers that the versions do not need to be matched. So, please, no more attempts to match these, OK?

Along with this, the NuGets have been updated too and the dependencies are not strict versions anymore. Check bellow what is showing in Visual Studio package manager for a NuGet package before and after.

Another improvement in the NuGets is that the required native version is now showing on the NuGet description. Making this visible removes the obscurity behind it and this can be checked visually and programmatically.

This native version is what the target device has to have support for. The native version available can be checked in the Device Explorer in Visual Studio. Bellow you can see the device capabilities of a target that has support for the above NuGet.

Every class library is now free from this slave dependency and, from now on, will have its version bumped only when there is a real need to.

The outcome of all this is that now we can start dealing with nanoFramework NuGets like we usually do with any other NuGet package: consume as needed and update when needed, not because we are forced to.

Trust all this will make everyone’s life easier and remove a lot of the friction that was around nanoFramework NuGets.

Have fun! 🙂

Deployment image generator

nanoFramework Visual Studio extension (both VS2017 and VS2019 versions) just got a new improvement: the ability to generate a “deployment image”. And what the heck is a “deployment image” you ask? Let me explain with a bit more detail.

To run a C# application a nanoDevice must have on its storage (which is a flash memory on all current target platforms) the following bits:

  • The nanoBooter responsible to perform the cold boot of the CPU and provide a mean to perform updates and a safe place when the CLR is messed up for some reason. This is valid unless the platform has to use it’s own, which is the case with ESP32 and the recently added TI CC32200SF.
  • The nanoCLR which comprises the IL execution engine, the CLR and the native parts of all the class libraries that the device has support for.
  • The configuration block. Optional and only required for devices that are network enabled to store network related stuff. Specifically, network configurations, certificates and Wi-Fi profiles.
  • The PEs (portable executable) of the managed application and the assemblies it references, like class libraries or others.

All those are made available in different occasions and flashed using different tools.

  • nanoBooter and nanoCLR are made available after compiling the nf-interpreter or by downloading them from our Bintray repository. These are flashed using the appropriate tool for the platform. This would be the nanoFramework flasher tool for ESP32, ST-LINK Utility or DfuSe for STM32 and Uniflash for TI.
  • The configuration block is written by the C# application itself or by using the Network Configuration dialog box available in the Visual Studio extension.
  • The PEs of the managed application (and referenced assemblies) are available upon a successful build of a Solution in Visual Studio. Those are deployed to the nanoDevice when hitting the “Deploy” option for the C# Project or when starting a debug session on Visual Studio.

If one is using nanoFramework to deploy stuff on a couple of boards the above is quite all right and works perfectly. Now, if you need to commission several boards on a production run or for a field test using a few dozen boards, things start to get complicated and time consuming. You’ll need to, at least, use a couple of different tools and possibly connect and disconnect each board a couple of times.

There is already a very handy feature which is the generation of a binary file with the bundle of all the PEs (application and referenced assemblies) that can be used to flash the “application” on a target that has already been loaded with the nanoBooter & nanoCLR. Yes, that’s the .bin file with the assembly name that you can find on the project output folder after a successful build.

nf-app-binary

We the recent improvement this was taken to the next level: generating a complete deployment image. Yes, you read it correctly, COMPLETE. With all the above: nanoBooter, nanoCLR, PEs and configuration block.

The nanoBooter, nanoCLR and configuration block are dumped from the connected target flash and cached (because that’s a lengthy operation). When the deploy operation occurs (and the PEs are generated and made available) the Visual Studio extension cooks everything together and spits a nice binary file with the full package.

nf-deployment-image-bin.png

This is working right now for STM32 targets only. Support for other platforms where this programming approach is suitable will follow.

The binary file can be flashed into the device using ST-LINK Utility or, if you’re working with an mbed enabled ST board (which all recent DISCOVERY and NUCLEO boards are), you can just drop it at the disk drive that shows on Windows Explorer and that’s burned in the flash in a couple of seconds. How cool is this?

Enough technicalities let’s see this working! 🙂

Enable the deployment image generation in the (new) settings dialog available in Device Explorer.

nf-enable-deployment-image-generator.png

You can optionally include the configuration block coming from the “seed” device. If you don’t, the region corresponding to the configuration block will be flashed with an empty content.

Just bellow this, you can find the configurations about the flash dump files cache. The options are: caching to the project output folder (which is the default) or in a location that you can specify.

All the above settings are persisted in you Visual Studio user account.

When you hit deploy or start a debug session, the magic happens, and the image is generated.

Something worth noting: the flash contents need to be dumped when they are not available on cache and this can take a few seconds before it completes. So be patient and know that this will happen only once for each device.
If you have a lot of devices and work on several projects at the same time, it’s probably wiser to use a central cache…

Now that we have the deployment image, let’s check it out.

Fire up ST-LINK Utility and connect the board. I’m using a STM32F769I-DISCO for this example.

nf-st-link-utility-connected

The board is already flashed with nanoBooter and nanoCLR and a debug session has been started previously with the Blinky application (meaning that the required PEs are there too). So, it has everything needed to blink the LED. Which it’s doing.

[wpvideo JCaz3qT8]

Next let’s load the file with the deployment image binary.

nf-st-link-utility-open-file

ST-LINK Utility has a nice comparing tool that we’ll use to compare the contents of the deployment image binary and what’s in the device flash.

nf-stlink-compare.png

We need to compare all the flash content so we’ll enter the flash start address next, which is 0x08000000 for this device.

nf-stlink-compare-start-address.png

The file contents are loaded next and the compare operation starts. I’m guessing that ST-LINK is very thorough on this because the operation takes a lot of time to complete.

nf-stlink-compare-progress.png

And voilà, if there were any doubts, the machine outputs it’s conclusions and confirms that both contents are identical!

nf-stlink-compare-success

Last test with this: use the disk drive flashing method.

Start by wiping the flash content using the “Full Chip Erase” command in ST-LINK Utility toolbar.

nf-stlink-full-chip-erase

After this you can disconnect the device.

Open Windows Explorer and locate the drive.

nf-mbed-disk-drive.png

Now open the folder where the deployment image file is located (that should be the project output directory) and simply drag and drop it on the drive representing the connected target. The upload will take a few seconds. After that operation is completed the MCU is reset, nanoBooter loads nanoCLR and finally the managed application is executed.

[youtube https://www.youtube.com/watch?v=jPheVSzfxu0&w=560&h=315]

This can be useful in many situations, like in production runs to load a test application, testing a bunch of boards, keeping a snapshot of a deployment, etc.

If you have an idea on how any of this can be improved, let us know, just send us a Tweet or join our Discord community. 😉

Have fun with nanoFramework!

To deploy, or not to deploy, that’s the question…

nanoFramework class libraries are composed of a managed part (written in C#) and the respective counterpart (written in C/C++) that is part of the firmware image that runs on the target.

As part of the usual development cycle there are improvements, bug fixes and changes. Some of those touch only the managed part, others only the native and others both. If the interface between them is not in sync: bad things happen.

In an effort to improve code quality and make developer’s life easier, two mechanisms have been implemented along the way. One was to have version numbers on both parts (that have to match) and the another was an improvement introduced on the deployment workflow that checks if the versions of the assemblies being deployed match the ones available in the target device. Pretty simple and straightforward, right?

Despite the simplicity of the mechanism, it has some draw backs. Occasionally it gets confusing because of apparent version mismatches caused by the fact that the develop branch is being constantly updated and the versions are bumped. Also, because the preview versions of the NuGet packages are always available in nanoFramework MyGet feed and not always on NuGet.

The other aspect that is not that positive is the need to have the versions in sync, which means that whenever the class library assembly version changes the native version must be bumped too. And that requires flashing the target device again. Most of the time without any real reason except that a version number was changed.

This is changing for better!

As of today, the native version number is independent of its managed counterpart. Meaning that it will change when it makes sense and not just because it has to mirror the managed version. Some of you are probably thinking right now that this will be a step back and has the potential to cause trouble with obscure version mismatches and deployment hell. This won’t happen because of something else that we are introducing on all class libraries (and base class), an Egg of Columbus, actually. There is new assembly attribute on all of those that declares which native version is required. Simple but effective.

This is will be used from now on by the deployment provider to validate if the target has all the required assemblies and versions to safely deploy the application.

Because these introduce several breaking changes, make sure you update the VS extension (2017 and 2019 versions available) and the NuGet packages on the Solutions you’re working for a smooth transition.

Happy coding with nanoFramework!

Support for Visual Studio 2019: check!

Last week we’ve published nanoFramework extension for Visual Studio 2019. Right on time before the official launch event on April 2, 2019. 😉

Being Visual Studio a corner stone in nanoFramework development experience, we wanted to show not only our commitment to our growing community by enabling them to keep up with Visual Studio release schedule, but also our appreciation to the Visual Studio team for providing us such an awesome tool.

With the release of the VS2019 version the extension for VS2017 will enter in maintenance mode. This means that we won’t be adding any new features to it. Only bug fixes and we’ll port also any fundamental changes that are required to keep up with new features that cause breaking changes.

As for the VS2019 extension, lots of good stuff is on the queue. We have plans to improve network configuration dialog, provide target updates right from Visual Studio and support for Unit Test.

Now go watch the launch event, install nanoFramework extension as soon as you get your VS2019 setup and stay tuned for exciting developments.

Follow us on Twitter, subscribe our YouTube channel and rate the extension on the marketplace. Do send your comments and suggest new features.

To wrap up, the usual punch: feel free to contribute with code, samples or any productive work to help the project and the community.

Have fun with the new VS2019 and nanoFramework!