arduino, AZ3166, MXChip

Programming the AZ3166 MXChip Azure DevKit – mapping virtual Arduino pins to physical digital I/O pins

Last time I wrote about getting started with the AZ3166 device – just a brief introduction to the on-board sensors and outputs, and I also wrote a simple application to demonstrate how to turn the red, green and blue LEDs on and off.

In that application, I mentioned that we can control the on/off status of the LEDs by writing a high or low value to three of the digital pins on the device. The numbers that I wrote digital values to were:

  • Red LED – Arduino pin 20
  • Green LED – Arduino pin 19
  • Blue LED – Arduino pin 39

WP_20171015_19_27_55_Pro

The photo above shows a Kitronik edge connector – but you can see that the number of pins only goes up to 16. So there was a mystery here – how is it that we switch the blue LED on in the Arduino code by accessing pin 39, when there aren’t actually 39 pins on the device?

Of course the answer is that the Arduino pin numbers don’t correspond to physical pins on the device – I prefer to think of them as virtual pins. I wasn’t able to find anyone else’s research on how to map physical pin numbers to Arduino virtual pin numbers, so I’ve mapped them out in the table below.

I’ve combined data from the official pin breakout notes on GitHub and some of my own research.

AZ3166 Edge Connector

So if I want to switch on the User LED, I need to change the status of physical pin 8 (i.e. pin 8 on the Kitronik connector). And if I want to access this pin through the Arduino IDE, I need to change the status of virtual pin 45 in the Arduino IDE.

int PIN_8 = 45;
 
void setup() {
  // initialize the pins as digital output.
  pinMode(PIN_8, OUTPUT);
 
}
 
void loop() {
  // turn user LED on
  digitalWrite(PIN_8, HIGH);
  delay(1000);

  // turn user LED off
  digitalWrite(PIN_8, LOW);
  delay(1000);
}

So with the table above, we can access the all the physical digital pins on the AZ3166 MXChip device with virtual pins numbers in Arduino code.

But what about analog I/O? Next time I’ll write about measuring external analog voltages using the AZ3166 device.


About me: I regularly post about Microsoft technologies – if you’re interested, please follow me on Twitter, or have a look at my previous posts here. Thanks!

arduino, IOT, MXChip

Programming the AZ3166 Azure DevKit – getting started

I’ve been looking forward to the release of the Azure AZ3166 “MXChip IoT DevKit” – a device with lots of sensors and outputs built into the device, that I can securely connect to IoT Hubs in the Azure cloud.

I’ve a few different posts planned about this device – in this post, I’ll write about the installation process, some small issues I found, and a basic application to interact with on-board LEDs by configuring pins as digital outputs.

WP_20171015_19_26_41_Pro

The device has the on-board features:

You can read more about the Azure AZ3166 here.

So because these are all on-board, that makes accessing them and using them really easy (particularly because all of the items above have great API documentation, and most have example code).

A couple of the features of this device I found very interesting were compatibility with Arduino code, and the connecting finger which has the same form factor as the BBC micro:bit – I’d like to find out how I can use this device to work with some of the breakout boards I use with my Arduino.

Software installation and getting started

There’s already a really good description of how to get started with this kit – check it out here. There’s no point in me repeating all of that here, so in summary:

mxchip_install

Things that didn’t go as well

This almost perfectly worked out of the box for me – but I like to share the small issues I experienced because I hope they’ll be roadsigns that help other developers avoid wasting time on the same problems.

  • The DevKit only works on 2.4GHz Wi-Fi. This is in the FAQ, but I didn’t read this right off the bat, and spent some time wondering why my hardware couldn’t find my Wi-Fi. Turned out that it was because I was running both 2.4GHz and 5GHz signals out of my router – when I changed the router settings to only broadcast on 2.4GHz, my device found the Wi-Fi straight away.
  • There are lots of warnings when you try to compile any application for the device through the Arduino or VSCode environments. The Arduino compiler output, even for ‘Hello World’ type applications, was absolutely littered with warnings. I’ve pasted a few below.
#warning toolchain.h has been replaced by mbed_toolchain.h, please update to mbed_toolchain.h [since mbed-os-5.3]
...
#warning wait_api.h has been replaced by mbed_wait_api.h, please update to mbed_wait_api.h [since mbed-os-5.3]
...
#warning sleep.h has been replaced by mbed_sleep.h, please update to mbed_sleep.h [since mbed-os-5.3]
...
#warning rtc_time.h has been replaced by mbed_rtc_time.h, please update to mbed_rtc_time.h [since mbed-os-5.3]

I spent some time uninstalling and re-installing different programs, and I even to the extent of installing the software on a fresh instance of Windows 10 in case another application or library conflict was causing this – it made no difference. But ultimately, these warnings didn’t impact any applications that I deployed.

arduino_output

  • Problems displaying serial output in the Arduino IDE Serial Monitor. I’m used to deploying applications to the Arduino using the Arduino IDE, specifically targeting a COM port at deployment time. I created an application for the AZ3166 with a few “Serial.println” statements, hoping to use the Serial Monitor built into the Arduino IDE to read the output. But after deploying to the AZ3166 DevKit device, I tried to open the Serial Monitor, and got an error message saying the IDE couldn’t find the COM1 port. The solution was to manually set the COM port through the “Tools -> Port” sub-menu, and the default port selected by the IDE isn’t actually the port that serial output is sent through.

A simple blinky application for the DevKit

There is already an example for the on-board RGB LED, but I wanted to work at a lower level to access on-board LEDs, rather than using existing libraries. I just needed to find out what Arduino pin numbers corresponded to the LEDs on the DevKit device.

I found that the numbers corresponding to the three basic LED colors are:

  • Red LED – Arduino pin 20
  • Green LED – Arduino pin 19
  • Blue LED – Arduino pin 39

I’ll post more about DevKit to Arduino pin mappings in a later post.

With this knowledge, it was very simple to create a variation on the standard “blinky” application, where I turn the red LED on and off, then the green LED, and finally the blue LED.

I’ve pasted the code below – just like regular Arduino C code.

int RED_LED = 20;
int GREEN_LED = 19;
int BLUE_LED = 39;
 
void setup() {
  // initialize the pins as digital output.
  pinMode(RED_LED, OUTPUT);
  pinMode(GREEN_LED, OUTPUT);
  pinMode(BLUE_LED, OUTPUT);
}
 
void loop() {
  // turn red LED on
  digitalWrite(RED_LED, HIGH);
  delay(1000);
 
  // turn red LED off
  digitalWrite(RED_LED, LOW);
  delay(1000);
 
  // turn green LED on
  digitalWrite(GREEN_LED, HIGH);
  delay(1000);
 
  // turn green LED off
  digitalWrite(GREEN_LED, LOW);
  delay(1000);
 
  // turn blue LED on
  digitalWrite(BLUE_LED, HIGH);
  delay(1000);
 
  // turn blue LED off
  digitalWrite(BLUE_LED, LOW);
  delay(1000);
}

So much for modifying the status of an LED on-board – now how about using code to adjust the digital statuses of pins on the connecting finger?

WP_20171015_19_27_55_Pro

First we have to be able to physically attach to the connecting finger, which I was able to do using a connector breakout. But I didn’t know what the numbers on the connector board corresponded to…next time I’ll write about using the connector.


About me: I regularly post about Microsoft technologies – if you’re interested, please follow me on Twitter, or have a look at my previous posts here. Thanks!

arduino

Two ways to initialize an array in C

I don’t often post about C, but I’ve been programming a lot in the Arduino world recently, and thought I’d post a quick couple of tips on a small programming challenge I encountered.

I needed to declare a character array (of length 64) – this is pretty simple.

char radioTextData[64];

And when I write the contents of this array to the Serial output…

for (short i = 0; i < sizeof(radioTextData); i++) {
    Serial.print(radioTextData[i]);
 }

…instead of seeing blank values, I see character values which were previously in the memory location used by my array variable.

So how can I make this array initially empty?

The hard way – write a function to loop over the array

As a .NET developer, this seemed like it should be pretty easy to me – in .NET variables are passed by reference so I can just pass the array into a method, and iterate over the array to set each value to whatever I want it to be (or use clever framework methods).

But when programming in C for the Arduino, it’s a little more complex to clear an array using a loop in a separate function. First we have to set up a pointer to the original array.

char radioTextData[64];
char* pointerToRadioTextData = radioTextData;

And now we have a pointer to the array, we can pass that to a function to process it – we also need to pass the size of the array because we can’t work that out from the pointer to the original array.

void clearArray(char* myArray, short sizeOfMyArray) {
    for (short i = 0; i < sizeOfMyArray; i++)
    {
        myArray[i] = ' ';
    }
}

The easy way – use memset

memset allows us to initialise an array to a specified character – so using just one line of code I can achieve the same result as in the first part of this post by passing the array, the size of the array, and the character that each element of the array to be initialised to.

memset(radioTextData, ' ', sizeof(radioTextData));

Summing up

So obviously to initialize and array, my code will use the easy way – it’s short, clear and elegant. But the technique of processing an array in C by passing a pointer to the start of the array is useful too.

.net core, arduino, Bifröst, IOT, Making, Raspberry Pi 3

Using .NET Core 2 on Raspbian Jessie to read serial data from an Arduino

I’ve previously written about how to use the System.IO.Ports library in .NET Core 2 to read serial data from an Arduino using a Windows 10 PC – but this library doesn’t work for Linux machines. This time I’m going to look at how to read data from an Arduino over USB with .NET Core running on a Raspberry Pi 3 with Raspbian Jessie.

There’s a few steps to getting this running.

  • First you’ll need:
    • A development machine (I’m using Windows 10),
    • A Raspberry Pi 3,
    • An Arduino,
    • A USB cable to link your Arduino and Raspberry Pi.
  • Next I’ll write a simple sketch and deploy it to my Arduino.
  • I’ll connect the Arduino to my Raspberry Pi 3, and check that the Pi can see my Arduino and the serial input using minicom.
  • Finally I’ll write and deploy a .NET Core application written in C# to my Raspberry Pi, and I’ll show how this application can read serial input from the Arduino.

As usual, I’ve uploaded all my code to GitHub and you can see it here.

For a few of the steps in this guide, I’ll refer to other sources – there’s not a lot of value in me writing a step by step guide for things which are commonly understood.

For example, I have a fresh install of Raspbian Jessie on my Raspberry Pi 3, and then I set up SSH on the Pi. I also use Putty, PSCP, Plink and Cake.net to deploy from my Windows machine to the Raspberry Pi (I’ve blogged in detail about this here).

Writing a sketch that writes serial data from the Arduino

In a previous post, I use VSCode to deploy a simple Arduino application that writes serial data. I could have used the Arduino IDE just as easily – and it’s widely known how to verify and upload sketches to the Arduino, so I’m not going to go into this part in great detail.

The code for the Arduino sketch is below:

int i = 0;
 
void setup(){
  Serial.begin(9600);
}
 
void loop(){
  Serial.print("Hello Pi ");
  Serial.println(i);
  delay(1000);
  i++;
}

One thing worth noting is that the Baud rate is 9600 – we’ll use this information later.

I can test this is writing serial data by plugging the Arduino into my Windows 10 development machine, and using VSCode or the Arduino IDE. I’ve shown a screenshot below of the serial monitor in my Arduino IDE, which just prints the text “Hello Pi” followed by a number. This confirms that my Arduino is writing data to the serial port.

screenshot.1502137097

Let’s test the Raspberry Pi can receive the serial data

Before writing a C# application in .NET Core to read serial data on my Raspberry Pi, I wanted to test that my Pi can receive data at all (obviously after connecting my Arduino to my Raspberry Pi using a USB cable).

This isn’t mandatory for this guide – I just wanted to definitely know that the Pi and Arduino communication was working before starting to write my C# application.

First, I need to find the name of the serial port used by the Arduino. I can find the names of serial ports by using PuTTY to SSH into my Pi 3, and then running the command:

ls -l /dev | grep dialout

Before connecting my Arduino UNO to my Raspberry Pi, this reports back two serial ports – ttyAMA0 and ttyS0.

screenshot.1502138314

After connecting my Arduino to my Raspberry Pi, this now reports back three serial ports – ttyACM0, ttyAMA0, and ttyS0.

screenshot.1502138155

Therefore I know the port used by my Arduino over USB is /dev/ttyACM0.

As an aside – not all Arduino boards will use the port /dev/ttyACM0. For example, I repeated this with my Arduino Nano and Arduino Duemilanove, and found they both use /dev/ttyUSB0, as shown below:

screenshot.1502211857

But for my Arduino Yun and my Arduino Primo, the port is /dev/ttyACM0.

screenshot.1502212282

So the point here is that you need to check what your port name is when you connect it to a Linux machine, like your Pi – the port name can be different, depending on what kind of hardware you connect.

Finally, if you’re interested in why “tty” is used in the Linux world for ports, check out this post.

Tools to read serial data

Minicom is a serial communication program which will confirm my Pi is receiving serial data from the Arduino. It’s very easy to install – I just used PuTTY to SSH into my Pi 3, and ran the command:

sudo apt-get install minicom

Then I was able to run the command below, using the port name (/dev/ttyACM0) and the Baud rate (9600).

minicom -b 9600 -o -D /dev/ttyACM0

If the Raspberry Pi is receiving serial data from the Arduino, it’ll be written to the SSH terminal.

Some posts I’ve read say it’s necessary to disable serial port logins to allow the Arduino to send messages to the Raspberry Pi, and modify files in the “/boot” directory – but on Jessie, I didn’t actually find this to be necessary – it all worked out of the box with my fresh install of Raspbian Jessie. YMMV.

Another alternative to prove serial communication is working is to install the Arduino IDE onto the Raspberry Pi, and just open the serial monitor on device. Again, installing the IDE on your Pi is very easy – just run the command below at a terminal:

sudo apt-get install arduino

This will even install an Arduino shortcut into the main Raspbian menu.

screenshot.1502139590.png

Once you’ve started the IDE and connected the Arduino to a USB port, select the serial port /dev/ttyACM0 (shown available on the Tools menu in the screenshot below):

screenshot.1502139935

Then open the serial monitor to check that the “Hello Pi” messages are coming through correctly (as shown below):

screenshot.1502140145

Writing the C# application

Now that I’m sure that the physical connection between the Arduino and Pi works, I can start writing the C# application.

TL:DR; I’ve uploaded my working code to GitHub here.

When writing my code, I wanted to stay close to the existing API provided by Microsoft in their library System.IO.Ports, which allows Windows machines to read from the serial port (I’ve blogged about this here). I was able to look at their source code on GitHub, and from this I designed the serial port interface below:

using Bifrost.IO.Ports.Core;
using System;
 
namespace Bifrost.IO.Ports.Abstractions
{
    public interface ISerialPort : IDisposable
    {
        int BaudRate { getset; }
 
        string PortName { getset; }
 
        bool IsOpen { getset; }
 
        string ReadExisting();
 
        void Open();
        
        event SerialDataReceivedEventHandler DataReceived;
 
        void Close();
    }
}

I like interfaces because consumers can use this interface, and don’t care if change my implementation behind the interface. It also makes my libraries more testable with mocking libraries. You can see this interface on GitHub here.

The next task was to design a .NET Core implementation for this interface which would work for Linux. I’ve previously done something similar to this for I2C communication, using P/Invoke calls (I’ve written about this here). After reading the documentation and finding some inspiration from another open source sample here, I knew I needed the following six P/Invoke calls:

[DllImport("libc", EntryPoint = "open")]
public static extern int Open(string portName, int mode);
 
[DllImport("libc", EntryPoint = "close")]
public static extern int Close(int handle);
 
[DllImport("libc", EntryPoint = "read")]
public static extern int Read(int handle, byte[] data, int length);
 
[DllImport("libc", EntryPoint = "tcgetattr")]
public static extern int GetAttribute(int handle, [Outbyte[] attributes);
 
[DllImport("libc", EntryPoint = "tcsetattr")]
public static extern int SetAttribute(int handle, int optionalActions, byte[] attributes);
 
[DllImport("libc", EntryPoint = "cfsetspeed")]
public static extern int SetSpeed(byte[] attributes, int baudrate);

These calls allow me to:

  • Open a port in read/write mode and get an integer handle to this port;
  • I can also get a list of attributes, specify the baudrate attribute, and then set these attributes.
  • Given the handle to the port, I can read from the port into an array of bytes.
  • Finally, I can also close the connection.

I’ll look at the most important elements below.

Opening the serial port

If we have instantiated a port with a name (/dev/ttyACM0) and a Baud rate (9600), we can use these P/Invoke calls in C# to open the port.

public void Open()
{
    int handle = Open(this.PortName, OPEN_READ_WRITE);
 
    if (handle == -1)
    {
        throw new Exception($"Could not open port ({this.PortName})");
    }
 
    SetBaudRate(handle);
 
    Task.Delay(2000);
 
    Task.Run(() => StartReading(handle));
}

You’ll notice that if the request to open the port is successful, it’ll return a non-negative integer, which will be the handle to the port that we’ll use throughout the rest of the class.

Setting the Baud rate is straightforward – we get the array of port attributes using the port’s handle, specify the Baud rate, and then send this array of attributes back to the device.

private void SetBaudRate(int handle)
{
    byte[] terminalData = new byte[256];
 
    GetAttribute(handle, terminalData);
    SetSpeed(terminalData, this.BaudRate);
    SetAttribute(handle, 0, terminalData);
}

I give the port a couple of seconds to settle down – I often find that the first few messages come through out of order, or with missing bytes – and then run the “StartReading” method in a separate thread using Task.Run.

Reading from the serial port

Reading from the port is quite straightforward too – given the handle, we just use the P/Invoke call “Read” to copy the serial data into a byte array which is stored as a member variable. Before invoking an event corresponding to a successful read, I check that there actually is valid data returned (i.e. the return value is non-negative), and that any data returned isn’t just a single newline character. If it passes this test, I pass control to the event handler for the DataReceived event.

private void StartReading(int handle)
{
    while (true)
    {
        Array.Clear(serialDataBuffer, 0, serialDataBuffer.Length);
 
        int lengthOfDataInBuffer = Read(handle, serialDataBuffer, SERIAL_BUFFER_SIZE);
 
        // make sure there is data in the buffer, and check if it's just one character that it's not just a newline character
        if (lengthOfDataInBuffer != -1 && !(lengthOfDataInBuffer == 1 && serialDataBuffer[0== ASCII_NEWLINE_CODE))
        {
            DataReceived.Invoke(thisnew SerialDataReceivedEventArgs());
        }
    }
}

Putting it all together

I’ve put my interfaces and implementations into separate .NET Standard libraries so that I can re-use them in my other .NET Core applications. And when I write a sample program for my Raspberry Pi to read from my Arduino, the implementation is very similar to the implementation that works for Windows x86/x64 devices reading from an Arduino (covered in this post).

using Bifrost.IO.Ports;
using Bifrost.IO.Ports.Core;
using System;
 
namespace SerialSample
{
    class Program
    {
        static void Main(string[] args)
        {
            var serialPort = new SerialPort()
            {
                PortName = "/dev/ttyACM0",
                BaudRate = 9600
            };
 
            // Subscribe to the DataReceived event.
            serialPort.DataReceived += SerialPort_DataReceived;
 
            // Now open the port.
            serialPort.Open();
 
            Console.ReadKey();
 
            serialPort.Close();
        }
 
        private static void SerialPort_DataReceived(object sender, SerialDataReceivedEventArgs e)
        {
            var serialPort = (SerialPort)sender;
 
            // Read the data that's in the serial buffer.
            var serialdata = serialPort.ReadExisting();
 
            // Write to debug output.
            Console.Write(serialdata);
        }
    }
}

Once I’ve compiled my project, and deployed it to my Raspberry Pi (using my build.cake script), I can SSH into my Pi and run the .NET Core application – and this displays the “Hello Pi” serial output being sent by the Arduino, as expected.

screenshot.1502145572

Wrapping up

It’s possible to read serial data from an Arduino connected by USB to a Raspberry Pi 3 using C#. Obviously the code here is just a proof of concept – it doesn’t use handshaking, parity bits or stop bits, and it only reads from the Arduino, but writing back to the serial port could be achieved using the P/Invoke call to the “write” function. Hopefully this post is useful to anyone trying to use serial communications between a Raspberry Pi 3 and an Arduino.


About me: I regularly post about .NET – if you’re interested, please follow me on Twitter, or have a look at my previous posts here. Thanks!

 

arduino, IOT, Making, PCB Manufacture

Upload a sketch to an Arduino UNO with bluetooth using the Adafruit Bluefruit EZ-Link breakout

I’m working on ways to make my Arduino UNO communicate with my Raspberry Pi 3 over a serial connection, and I’ve used a USB cable to connect the two devices together.

But because the Type-B USB connector on the Arduino is being used, I don’t have a convenient way to upload sketches to the Arduino UNO from my development machine.

I can obviously disconnect the USB connector from the Arduino UNO and connect it to my development machine, but this gets kind of old after a while, and I’d like an easier way to upload sketches.

So I dug deep into my box of electronic bits and pieces, and fortunately found I’ve got another way to do this – I can add bluetooth capability to my Arduino UNO with the Adafruit Bluefruit EZ-link breakout board.

First connect the board to the Arduino UNO

I could have done this with wires and a breadboard, but I decided to make a custom shields with some copper clad PCB board and my Shapeoko.

WP_20170803_11_23_20_Pro

Fortunately there was very little soldering to be done on my custom PCB as my soldering could be better!

WP_20170803_11_23_35_Pro

 

I designed the PCB according the pinout recommended by Adafruit, which is:

EZ-Link Arduino UNO
GND GND
DSR Not connected
V-IN 5V
Tx Digital Pin 0 (Rx)
Rx Digital Pin 1 (Tx)
DTR 1uF in series with Reset

Attaching the breakout board to a custom made PCB makes the whole device more self contained and I can also add other Arduino shields on top.

I found out afterwards that Adafruit actually sells something similar to this already – a Bluefruit EZ-Link Shield.

Now pair the Bluefruit board with a development machine

Adafruit provide some really good documentation for pairing the Bluefruit module with a Windows 7 machine – but I’ve written my own notes before for the Windows 10 operating system.

My Arduino is powered by the USB connection to my Raspberry Pi, so once I attached the shield to the Arduino the blue power light came on immediately. The next step was to pair the Bluefruit device with my development machine.

My machine has bluetooth v4.0 on board, but I could have used an after-market bluetooth dongle like this one – it’s important to get one that supports bluetooth v4.0, some of the cheaper dongles do not support v4.0.

From Windows 10, I typed “Bluetooth” into the search box on the taskbar, and the results gave me the option to select “Bluetooth and other devices settings”.

screenshot.1501708578

I clicked on the “+” button beside the text “Add Bluetooth or other device”, which opened the screen below.

screenshot.1501679214

I clicked on the Bluetooth option, which opened the screen below, and this shows the Adafruit EZ-Link device.

screenshot.1501679192

I selected the Adafruit device for pairing, and received the success message below.

screenshot.1501679253

So at this point, it’s possible to upload sketches to the Arduino through the Bluetooth COM port – and in the image below, you can see that even though my Arduino isn’t connected by USB cable to my development machine, the serial port COM6 is available to me.

screenshot.1501710670

I talked about how to use VSCode to develop and deploy to the Arduino last time, and it works exactly the same way in VSCode.

And as far as the Arduino is concerned, this is just another COM port, as if the Arduino was directly connected to the PC using a USB cable. I don’t need to do any further set up, and I can verify and upload my sketch to the Arduino UNO wirelessly through COM6 (it’ll probably be different on another machine). It’s a little bit slower to transfer a sketch over the air, but at least it’s wireless.

Wrapping up

This was a short post about how to wirelessly deploy sketches to the Arduino using the Adafruit Bluefruit EZ-Link breakout. When I can’t use the Arduino’s on board USB port, this device makes my Arduino development much more convenient. If you have this device in your toolkit, hopefully you find this post useful!


About me: I regularly post about .NET – if you’re interested, please follow me on Twitter, or have a look at my previous posts here. Thanks!

.net core, arduino, IOT

Using .NET Core 2 to read serial data from an Arduino UNO over USB

If you’ve worked with an Arduino and used a Windows development machine, you’ll probably have used the Arduino IDE to deploy code, and used the IDE’s built in serial monitor to read messages back from the Arduino device. And if you want to use these messages in a .NET application, there’s already good support in the .NET Framework – but what about .NET Core?

In this post, I’ll look at how to use VSCode to create an Arduino simple project which writes to a serial port, and deploy this to an Arduino Uno using VSCode. Then I’ll write about how to use the preview NuGet package to read this data using .NET Core. I’ll finish up with some issues I’ve observed.

Note – this article about .NET Core targets Windows 10 32-bit/64-bit editions – this won’t work if you’re targeting ARM devices with Windows 10 IoT Core (i.e. win10-arm). I’ll cover targeting the ARM platform in a later post.

Also, you’ll obviously need an Arduino for this – I’ve found an Arduino UNO is ideal.

This post has two main sections – setting up a example project on an Arduino using VSCode to write data to a serial port, and then how to access this data using a .NET Core application.

Writing data to a serial port with an Arduino

Setting up VSCode for Arduino development

First of all, you’ll need VSCode on your development machine – you can download it from here. I’ll not describe this in detail – it’s pretty much a point and click installer.

You’ll also need the Arduino IDE installed on your machine so VSCode can access the necessary libraries – you can download it from here. Again this is a very straightforward installation.

Next, install the Arduino extension for VSCode. There are great instructions here – but in summary, from VSCode:

  • Hit ‘Ctrl + P’
  • Type:
ext install vscode-arduino

At this point, you’ll have the Arduino extension for VSCode, presently at version 0.2.4.

Create an Arduino project in VSCode which writes to the serial port

From VSCode, you can create a new Arduino project with the following steps:

  • Create a folder on your development machine to hold the Arduino project – I’ve called mine ArduinoSerialExample
  • Open this folder in VSCode.
  • In VSCode, hit ‘Ctrl + Shift + P’ to open the VSCode Command Palette.
  • Type: Arduino: Initialize – VSCode will offer to create a file with extension app.ino.

screenshot.1501514685

  • Rename this to ArduinoSerialExample.ino. It’s important that this file (also known as an Arduino sketch) has the same name as the parent directory.
  • At this point, VSCode will ask what Arduino device is being used – I’m using an Arduino UNO, so I selected this from the list.

screenshot.1501514840

Your VSCode workspace is now initialised for Arduino development.

  • Update the code in the ArduinoSerialExample.ino file to have the contents shown below.
int i = 0;
 
void setup(){
  Serial.begin(9600);
}
 
void loop(){
  Serial.print("Hello Pi ");
  Serial.println(i);
  delay(1000);
  i++;
}

Important tip – if you copy and paste into VSCode, make sure you don’t accidentally copy unexpected unicode characters, as these will cause compiler errors.

  • Now hit ‘Ctrl + Shift + R’ to compile (also known as Verify) the script – if everything works, you should see an output similar to the text below.
[Starting] Verify sketch - ArduinoSerialExample.ino
Loading configuration...
Initialising packages...
Preparing boards...
Verifying...

Sketch uses 1,868 bytes (5%) of program storage space. Maximum is 32,256 bytes.
Global variables use 198 bytes (9%) of dynamic memory, leaving 1,850 bytes for local variables. Maximum is 2,048 bytes.
[Done] Finished verify sketch - ArduinoSerialExample.ino

Test this project works with a real Arduino

There’s a couple of last steps – connecting the physical Arduino to your development machine, and choosing the serial port.

If you look at the bottom right corner of VSCode, you should see that there’s still a prompt to select the serial port (as shown below).

screenshot.1501515586

Once I plugged my Arduino UNO into a USB port on my machine, I was able to click on theprompt (highlighted in a red box in the image above), and VSCode prompts me to select a serial port, as shown below.

screenshot.1501518211

I selected COM4, and this updates VSCode to show the serial port in the bottom right corner of the screen, as shown below.

screenshot.1501278934

I’m now ready to rest the Arduino is writing to the serial port.

I can upload the sketch to the Arduino by hitting ‘Ctrl + Shift + U’ – this will re-compile the sketch and upload it to the Arduino.

Next, hit open the command palette again (by hitting ‘Ctrl + Shift + P’, and type ‘Arduino Open Serial Monitor’, and select the option to open the Serial Monitor from the dropdown list.

screenshot.1501519010

The serial monitor opens, and I’m able to see output being logged to the console from the Arduino through the serial port COM4, as shown below.

screenshot.1501518933

Accessing the serial port data on a PC using .NET Core

TL:DR; I’ve uploaded the project to GitHub here.

First set up the .NET Core 2 solution – a console project and a .NET Standard 2.0 class library

Create a new project to hold your .NET solution. I like to manage solutions using the command line – I create a solution using the command:

dotnet new sln -n ReadSerialDataFromArduino

Inside this solution folder, create a new .NET Core console project – I do this using the command:

dotnet new console -n ReadFromArduino

Also create a new .NET Standard 2.0 library project inside the solution folder – again, I do this using the command:

dotnet new classlib -n ReadSerialInputFromUSB

Now we can add these two projects to the solution using the commands below

dotnet sln add .\ReadFromArduino\ReadFromArduino.csproj
dotnet sln add .\ReadSerialInputFromUSB\ReadSerialInputFromUSB.csproj

And we can see the projects in the solution using the command below:

dotnet sln list

And this command presents the expected output of:

Project reference(s)
--------------------
ReadFromArduino\ReadFromArduino.csproj
ReadSerialInputFromUSB\ReadSerialInputFromUSB.csproj

Finally for this section, I want to add the library as a reference to my console application with the command:

dotnet add .\ReadFromArduino\ReadFromArduino.csproj reference .\ReadSerialInputFromUSB\ReadSerialInputFromUSB.csproj

Add the .NET Core System.IO.Ports preview package

The System.IO.Ports package (available here on nuget.org) allows access to the serial port through a .NET Core application. I can add this to my .NET Standard 2.0 class library by navigating into the ReadSerialInputFromUSB directory, and run the command below:

dotnet add package System.IO.Ports --version 4.4.0-preview2-25405-01

So now the project structure is is place – we can add the bits of code that actually do things.

Let’s use C# to list what serial ports are available to us. I’ve created a class in the ReadSerialInputFromUSB project named SerialInformation, and added a static method called GetPorts().

using System;
using System.IO.Ports;
 
namespace ReadSerialInputFromUSB
{
    public class SerialInformation
    {
        public static void GetPorts()
        {
            Console.WriteLine("Serial ports available:");
            Console.WriteLine("-----------------------");
            foreach(var portName in SerialPort.GetPortNames())
            {
                Console.WriteLine(portName);
            }
        }
    }
}

And we can access this through the main method in the ReadFromArduino project:

using ReadSerialInputFromUSB;
 
namespace ReadFromArduino
{
    class Program
    {
        static void Main(string[] args)
        {
            SerialInformation.GetPorts();
        }
    }
}

If we build this and run the project (using dotnet build and dotnet run) the output is:

Serial ports available:
-----------------------
COM4

This is exactly what we’d expect from earlier, where VSCode identified COM4 as the port being used by the Arduino.

And if we can get the data from the Arduino into a variable and write to the console, we can do that by using the DataReceived event and using the ReadExisting() method on the serial port object, as shown below:

public void ReadFromPort()
{
    // Initialise the serial port on COM4.
    // obviously we would normally parameterise this, but
    // this is for demonstration purposes only.
    this.SerialPort = new SerialPort("COM4")
    {
        BaudRate = 9600,
        Parity = Parity.None,
        StopBits = StopBits.One,
        DataBits = 8,
        Handshake = Handshake.None
    };
 
    // Subscribe to the DataReceived event.
    this.SerialPort.DataReceived += SerialPortDataReceived;
 
    // Now open the port.
    this.SerialPort.Open();
}
 
private void SerialPortDataReceived(object sender, SerialDataReceivedEventArgs e)
{
    var serialPort = (SerialPort)sender;
 
    // Read the data that's in the serial buffer.
    var serialdata = serialPort.ReadExisting();
 
    // Write to debug output.
    Debug.Write(serialdata);
}

I can call this in my console project’s main method using the code below:

static void Main(string[] args)
{
    SerialInformation.GetPorts();
 
    var serialInformation = new SerialInformation();
 
    serialInformation.ReadFromPort();
 
    Console.ReadKey();
 
    serialInformation.SerialPort.Close();
}

So when I run this console application, the COM4 serial port is opened, and writes whatever it receives to the debug output.

You can see the source code for the Serial.IO.Ports library on GitHub in the CoreFX library, and there’s access to the nightly builds on myget.org.

This library is great for connecting to (and reading from) serial ports using a .NET Core application running on a Windows x32/x64 machine. However, one issue is this library doesn’t work with ARM – either for Windows 10 IoT Core or for Linux.

Wrapping up

Using the Serial.IO.Ports preview library available on NuGet, it’s possible to read from serial ports using a .NET Core 2 application on a Windows 32-bit/64-bit machine, and I’ve a very simple example of how to do this available on GitHub here. So far there’s not an implementation in the Serial.IO.Ports library which works for ARM architectures, but I’ll look at options for closing this gap in future posts.


About me: I regularly post about .NET – if you’re interested, please follow me on Twitter, or have a look at my previous posts here. Thanks!

.net, Cake, Continuous Integration, Raspberry Pi 3, UWP

Deploy a UWP application to a Windows 10 device from the command line with Cake

I’ve wanted to improve my continuous integration process for building, testing and deploying UWP applications for a while. For these UWP apps, I’ve been tied to using VS2017 for build and deploy operations – and VS2017 is great, but I’ve felt restricted by the ‘point and click’ nature of these operations in VS2017.

Running automated tests for any .NET project is well documented, but until relatively recently I’ve not had a really good way to use a command line to:

  • build my UWP project and solution,
  • run tests for the solution,
  • build an .appxbundle file if the tests pass, and
  • and deploy the appxbundle to my Windows 10 device.

Trying to find out what’s going on under the hood is the kind of challenge that’s catnip for me, and this is my chance to share what I’ve learned with the community.

This is part of a series of posts about building and deploying different types of C# applications to different operating systems.

If you follow this blog, you’ll probably know I normally deploy apps to my Raspberry Pi 3, but the principles in here could be applied to other Windows 10 devices, such as an Xbox or Windows Phone.

Step 1 – Create the demo UWP and test projects.

I’ll keep the description of this bit quick – I’ll just use the UWP template in Visual Studio 2017 – it’s only a blank white screen but that’s ok for this demonstration.

screenshot.1500076564

I’ve also created an empty unit test project – again the function isn’t important for this demonstration, we just need a project with a runnable unit test.

screenshot.1500076646

I’ve written a simple dummy ‘test’, shown below – this is just created for the purposes of demonstrating how Cake can run a Unit Test project written using MSTest:

using Microsoft.VisualStudio.TestTools.UnitTesting;
 
namespace UnitTestProject2
{
    [TestClass]
    public class UnitTest1
    {
        [TestMethod]
        public void TestMethod1()
        {
            Assert.IsTrue(true);
        }
    }
}

Step 2: Let’s build our project and run the tests using Cake

Open a powershell prompt (I use the package manager console in VS2017) and navigate to the UWP project folder. Now get the Cake bootstrapper script and example Cake build file using the commands below:

Invoke-WebRequest http://cakebuild.net/download/bootstrapper/windows -OutFile build.ps1

Invoke-WebRequest https://raw.githubusercontent.com/cake-build/example/master/build.cake -OutFile build.cake

I edited the build.cake file to have the text below – this script cleans the binaries, restores the NuGet packages for the projects, builds them and runs the MSTests we created.

#tool nuget:?package=NUnit.ConsoleRunner&version=3.4.0
//////////////////////////////////////////////////////////////////////
// ARGUMENTS
//////////////////////////////////////////////////////////////////////

var target = Argument("target", "Default");
var configuration = Argument("configuration", "Release");

//////////////////////////////////////////////////////////////////////
// PREPARATION
//////////////////////////////////////////////////////////////////////

// Define directories.
var buildDir = Directory("./App3/bin") + Directory(configuration);

//////////////////////////////////////////////////////////////////////
// TASKS
//////////////////////////////////////////////////////////////////////

Task("Clean")
    .Does(() =>
{
    CleanDirectory(buildDir);
});

Task("Restore-NuGet-Packages")
    .IsDependentOn("Clean")
    .Does(() =>
{
    NuGetRestore("../App3.sln");
});

Task("Build")
    .IsDependentOn("Restore-NuGet-Packages")
    .Does(() =>
{
    if(IsRunningOnWindows())
    {
      // Use MSBuild
      MSBuild("../App3.sln", settings =>
        settings.SetConfiguration(configuration));
    }
    else
    {
      // Use XBuild
      XBuild("../App3.sln", settings =>
        settings.SetConfiguration(configuration));
    }
});

Task("Run-Unit-Tests")
    .IsDependentOn("Build")
    .Does(() =>
{
    MSTest("../**/bin/" + configuration + "/UnitTestProject2.dll");
});

//////////////////////////////////////////////////////////////////////
// TASK TARGETS
//////////////////////////////////////////////////////////////////////

Task("Default")
    .IsDependentOn("Run-Unit-Tests");

//////////////////////////////////////////////////////////////////////
// EXECUTION
//////////////////////////////////////////////////////////////////////

RunTarget(target);

Cake’s built in benchmarking shows the order in which the tasks are executed

Task Duration 
--------------------------------------------------
Clean                  00:00:00.0124995 
Restore-NuGet-Packages 00:00:03.5300892 
Build                  00:00:00.8472346 
Run-Unit-Tests         00:00:01.4200992 
Default                00:00:00.0016743 
--------------------------------------------------
Total:                 00:00:05.8115968

And obviously if any of these steps had failed (for example if a test failed), execution would stop at this point.

Step 3: Building an AppxBundle in Cake

If I want to build an appxbundle for a UWP project from the command line, I’d run the code below:

MSBuild ..\App3\App3.csproj /p:AppxBundle=Always /p:AppxBundlePlatforms="x86|arm" /Verbosity:minimal

There’s four arguments have told MSBuild about:

  • The location of the csproj file that I want to target
  • I want to build the AppxBundle
  • I want to target x86 and ARM platforms (ARM doesn’t work on its own)
  • And that I want to minimise the verbosity of the output logs.

I could use StartProcess to get Cake to run MSBuild in a task, but Cake already has methods for MSBuild (and many of its parameters) baked in. For those parameters which Cake doesn’t know about, it’s very easy to use the WithProperty fluent method to add the argument’s parameter and value. The code below shows how I can implement the command to build the AppxBundle in Cake’s C# syntax.

var applicationProjectFile = @"../App3/App3.csproj";
 
// ...

MSBuild(applicationProjectFile, new MSBuildSettings
    {
        Verbosity = Verbosity.Minimal
    }
    .WithProperty("AppxBundle", "Always")
    .WithProperty("AppxBundlePlatforms", "x86|arm")
);

After this code runs in a task, an AppxBundle is generated in a folder in the project with the path:

AppPackages\App3_1.0.0.0_Debug_Test\App3_1.0.0.0_x86_arm_Debug.appxbundle

The path and file name isn’t massively readable, and is also likely to change, so I wrote a short method to search the project directories and return the path of the first AppxBundle found.

private string FindFirstAppxBundlePath()
{
    var files = System.IO.Directory.GetFiles(@"..\", @"*.appxbundle", SearchOption.AllDirectories);
    
    if (files.Count() > 0)
    {
        return files[0];
    }
    else
    {
        throw new System.Exception("No appxbundle found");
    }
}

Now that I have the path to the AppxBundle, I’m ready to deploy it to my Windows device.

Step 4: Deploying the AppxBundle

Microsoft have provided a command line tool in the Windows 10 SDK for deploying AppxBundles – this tool is called WinAppDeployCmd. The syntax used to deploy an AppxBundle is:

WinAppDeployCmd install -file "\MyApp.appxbundle" -ip 192.168.0.1

It’s very straightforward to use a command line tool with Cake – I’ve blogged about this before and how to use StartProcess to call an executable which Cake’s context is aware about.

But what about command line tools which Cake doesn’t know about? It turns out that it’s easy to register tools within Cake’s context – you just need to know the path to the tool, and the code below shows how to add the UWP app deployment tool to the context:

Setup(context => {
    context.Tools.RegisterFile(@"C:\Program Files (x86)\Windows Kits\10\bin\x86\WinAppDeployCmd.exe");
});

If you don’t have this tool on your development machine or CI box, it might be because you don’t have the Windows 10 SDK installed.

So with this tool in Cake’s context, it’s very simple to create a dedicated task and pull the details of this tool out of context for use with StartProcess, as shown below.

Task("Deploy-Appxbundle")
	.IsDependentOn("Build-Appxbundle")
	.Does(() =>
{
    FilePath deployTool = Context.Tools.Resolve("WinAppDeployCmd.exe");
 
    Information(appxBundlePath);
 
    var processSuccessCode = StartProcess(deployTool, new ProcessSettings {
        Arguments = new ProcessArgumentBuilder()
            .Append(@"install")
            .Append(@"-file")
            .Append(appxBundlePath)
            .Append(@"-ip")
            .Append(raspberryPiIpAddress)
        });
 
    if (processSuccessCode != 0)
    {
        throw new Exception("Deploy-Appxbundle: UWP application was not successfully deployed");
    }
});

And now we can run our Cake script to automatically build and deploy the UWP application – I’ve pasted the benchmarking statistics from Cake below.

Task                     Duration
--------------------------------------------------
Clean                    00:00:00.0821960
Restore-NuGet-Packages   00:00:09.7173174
Build                    00:00:01.5771689
Run-Unit-Tests           00:00:03.2204312
Build-Appxbundle         00:01:09.6506712
Deploy-Appxbundle        00:02:13.8439852
--------------------------------------------------
Total:                   00:03:38.0917699

And to prove it was actually deployed, here’s a screenshot of the list of apps on my Raspberry Pi (from the device portal) before running the script…

screenshot.1500907026

…and here’s one from after – you can see the UWP app was successfully deployed.

screenshot.1500907690

I’ve uploaded my project’s build.cake file into a public gist – you can copy this and chan-ge it to suit your particular project (I haven’t uploaded a full UWP project because sometimes people have issues with the *.pfx file).

Wrapping up

I’ve found it’s possible to build and deploy a UWP app using the command line, and beyond that it’s possible to integrate the build and deployment process into a Cake script. So even though I still create my application in VS2017 – and I’ll probably keep using VS2017 – it means that I have a much more structured and automated integration process.


About me: I regularly post about .NET – if you’re interested, please follow me on Twitter, or have a look at my previous posts here. Thanks!