TinyCLR OS

Last modified May 10, 2017

TinyCLR OS is our new take on .NET Micro Framework. You can learn more about it in the announcement.

To get started, install Visual Studio 2017 with the .NET Desktop Development workload and then install the VSIX from the TinyCLR OS install package. Next, flash the provided firmware to your device using TeraTerm or another serial program. Then start a new TinyCLR Application project in Visual Studio 2017 under C# -> TinyCLR, write some code, and press F5 to start your application.

You'll also need to create a local NuGet feed and place the provided library packages there until we upload them to the NuGet public gallery.

Since TinyCLR installs side by side with NETMF, you can continue using your existing NETMF projects. You can also reflash the NETMF firmware to your device at any time.

The libraries available today are limited. They will continue to change and evolve as we go forward to make sure we are up to date and consistent with the current desktop BCL and UWP APIs and that we have a compelling feature set for embedded devices.

We plan on following SemVer for all version numbers and keeping assembly and firmware checksum compatible within a major.minor version. If a change in a library does not change the checksum or otherwise go against SemVer, it'll be a patch release. It is easy to verify that a given assembly and firmware are compatible: just make sure they have the same major and minor version.

Roslyn

Even better is that since we are using the Roslyn compiler with VS2017, you get a lot of C# 6 and C# 7 features (those that depend on generics do not work). While we have not added support for the missing .constraint IL prefix yet, we have not noticed Roslyn producing it in our tests. We've quickly tested the below features and confirmed them to work. Let us know if you run into any cases that fail on the device but work in a desktop application. See New Language Features in C# 6 and What’s New in C# 7.0 for details.

Releases

0.4.0 on 2017-05-10

Notes

This release primarily fixes several bugs; implements more of the serial API; adds DataReader, DataWriter, and Marshal classes; and reworks a lot of the BrainPad API. A new Storage library was added that moves some large members (like DataReader) out of Devices that you may not always needed. There is more to be added to this library down the road. SignalGenerator, SignalCapture, and PulseFeedback were renamed to match the Windows 10 counterparts. Their API will be updated to match as well in a future release.

The Marshal class under System.Runtime.InteropServices can be used like the old Register and AddressSpace classes to read and write memory. It also adds allocating and releasing unmanaged memory from the managed side that can be manipulated from the other members.

You can see a quick example on using the new serial API here. You must use either the DataReader and DataWriter classes or use the WindowsRuntimeBufferExtensions to manipulate a Buffer since the internal array is no longer publicly accessible to match the UWP API. Pay attention to the Load and Store members. You can't read before calling Load and writes do not get flushed until you call Store.

There has been no change to the G120 and G400 bootloaders in this release so you do not need to update them if you already have them on your device from the 0.3.0 release.

After flashing the firmware for the first time on any device, Windows may still use the old NETMF USB IDs preventing the device from being seen by TinyCLR. Uninstall the device from the Device Manager and reinstall it to fix it. To update the firmware on pre-Windows 10 machines, you will need the bootloader drivers provided by our existing 2016 R1 NETMF SDK.

Libraries

Changes

Known Issues

Firmware

Changes

Known Issues

Extension

Changes

Known Issues

0.3.0 on 2017-04-06

Notes

This release has several API additions. Some were added as features themselves (software SPI, SignalGenerator, etc) while others were added to support certain features (the VB runtime, string.Format, MemoryStream and IntPtr for Drawing, etc). We're working to align ourselves with the various .NET Reference Sources available. You'll also see many new icons throughout, application templates for the BrainPad, and common item templates. The NuGet packages that have dependencies (such as on Core), now require the major and minor versions to match. For example, the 0.3.0 Devices library depends on Core [0.3.0,0.4.0). This is to further our use of SemVer so that the native interop checksum only changes in major and minor versions. See the NuGet docs for more information.

The biggest addition is the drawing library. It was designed to mirror System.Drawing from the desktop. The basic API is there but there is still more work to be done. To support this, a DisplayController was added to the devices library to configure the display. Since there is no config yet you need to configure the display every time your program starts. A notable change from NETMF is calling flush on a drawing surface the size of the display will no longer draw to the display. Only drawing surfaces created from the FromHdc method passing in the Hdc value from the DisplayController will flush to the display. At this time, only bmp images are supported. Make sure you add a reference to GHIElectronics.TinyCLR.Drawing if using bitmap or font resources. Since it's in NuGet now it isn't automatically added.

Support for Visual Basic has also been reenabled. One important thing to keep in mind is that there is no longer a Microsoft.VisualBasic assembly. We are using the embedded runtime option provided by Roslyn. It relies on several APIs being present in the core library. We added several of the key APIs needed to enable common usage scenarios. If you find you're getting cryptic compile errors from locations not in your code, let us know so we can evaluate what additional APIs are required.

Since the UWP API only supports a controller wide frequency, we had to rework PWM a little bit. There is no longer one controller like there is for GPIO, instead one controller exists for each frequency source. On devices like the G30 and G80, this is a timer. On devices like the G400, there are independent registers for each channel (so unfortunately there will be one controller per channel). The pins library has been updated to organize PwmPin around controllers. SignalGenerator, SignalCapture, and PulseFeedback have also been added, but their APIs will change in a future release to match the UWP style. You can also now change what gets returned by GetDefault calls on the various controllers by updating LowLevelDevicesController.DefaultProvider.

The Diagnostics namespace now matches the desktop version more closely. WriteLineIf and Assert were added to Debug and Trace was added as well. All methods on Debug and Trace are marked with the Conditional attribute as expected using the DEBUG and TRACE constants respectively. There's also now a Listeners property on each. This is a collection that you can add to so you can receive whatever is written to Trace or Debug by registering a class derived from TraceListener. As on the desktop, both Trace and Debug share the same listener collection. By default, the collection is populated with a listener that prints to the debug transport which is now at Debugger.Log. Collect and GetTotalMemory were added to GC. Note that GetTotalMemory returns the amount of memory used, not free, to match the desktop. We're investigating APIs to return the amount free.

The last notable change is that we implemented IntPtr and UIntPtr. For now, they're only used as the type of the Hdc property in drawing. We expect them to be used in more places going forward. Since these two types map to native int and native unsigned int in the CLR and the managed compilers emit those types when they encounter IntPtr or UIntPtr, we have also added initial support for those types in the interpreter and runtime as well. Let us know if you encounter any weird or hard to explain runtime issues.

This release also includes the firmware for the G400. It requires an updated bootloader from the one provided on the G400 bootloader installation page. Simply download the bootloader installer from the installation page and replace Bootloader.bin with the bootloader provided in the TinyCLR download package (making sure to rename it to Bootloader.bin). This updated bootloader can still be used to install the NETMF G400 firmware. It will eventually replace the one provided on the installation page.

After flashing the firmware for the first time on any device, Windows may still use the old NETMF USB IDs preventing the device from being seen by TinyCLR. Uninstall the device from the Device Manager and reinstall it to fix it. To update the firmware on pre-Windows 10 machines, you will need the bootloader drivers provided by our existing 2016 R1 NETMF SDK.

You can see some examples of the new APIs added in this release here.

Libraries

Changes

Known Issues

Firmware

Changes

Known Issues

Extension

Changes

Known Issues

0.2.0 on 2017-03-07

Notes

You cannot use projects you made for the 0.1.0 version. You must recreate them and re-add your code files because of the changes to the project templates to make them more closely align them with the desktop .NET templates -- you'll notice the only difference is a few properties which prevent inclusion of reference assemblies. The templates also use the .NET Framework 4.5.2 target framework. This is only for NuGet compatibility going forward and does not mean you can use other libraries targeting that framework. This was done in anticipation of broader project system support of the new PackageReference format currently used in .NET Core which fails with unknown target frameworks.

The MSBuild package is no longer provided or required. The metadata processor tool has moved internally to the extension and is invoked during deployment to the device. This means that pe and pdbx files are no longer redistributed with their assemblies -- they appear in a pe folder under the output directory when you deploy. We have also rewritten how dependencies are detected for deployment. If you notice any weird failures around assembly resolution or deployment, let us know and send us the entire project as-is so we can diagnose it.

The information displayed while deploying to the device has also been improved to show more information about what is going on and what stage the deployment is in. We've also reworked incremental deployment so that assemblies are deployed one to a flash sector (if space allows) to enable re-deploying only the assemblies that have changed on a sector by sector basis. This greatly increases deployment speed on devices which a large number of flash sectors allocated to deployment.

This release also includes the firmware for the G120 and G120E. Because the current GHI bootloader on the G120 expects to load TinyBooter, we have provided a second stage bootloader with this preview that you must deploy using the existing GHI bootloader as if you were deploying TinyBooter. Once it is deployed and you restart the device, you'll notice that it starts our newer GHI bootloader 2.0. You can then use this second bootloader to deploy the TinyCLR OS firmware. Asserting LDR0 will enter the second bootloader while asserting both LDR0 and LDR1 will enter the original bootloader and allow you to return to NETMF.

After flashing the firmware the first time, Windows may still use the old NETMF USB IDs preventing the device from being seen by TinyCLR. Uninstall the device from the Device Manager and reinstall it to fix it. To update the firmware on pre-Windows 10 machines, you will need the bootloader drivers provided by our existing 2016 R1 NETMF SDK.

Core

Changes

Known Issues

Devices

Changes

Known Issues

Pins

Changes

Known Issues

Firmware

Changes

Known Issues

Extension

Changes

Known Issues

0.1.0 on 2016-12-16

Known Issues

Additions

Leave feedback about this document.
Let us know if the information presented here was accurate, helpful and if you have any suggestions.
Leave feedback about this document.
Let us know if the information presented here was accurate, helpful and if you have any suggestions.

* Indicates required fields.
This form is only for feedback not support.
Review our how to find information guide on locating helpful resources.