Entries:
Comments:
Posts:

Loading User Information from Channel 9

Something went wrong getting user information from Channel 9

Latest Achievement:

Loading User Information from MSDN

Something went wrong getting user information from MSDN

Visual Studio Achievements

Latest Achievement:

Loading Visual Studio Achievements

Something went wrong getting the Visual Studio Achievements

What Is an Arduino Shield and Why Should My Netduino Care?

Download

Right click “Save as…”

C9 Netduino Shield Series - Using Arduino Shield with Netduino - Part I

clip_image001_thumb1 
Photo courtesy of John Boxall

Introduction

When the Arduino Duemilanove microcontroller appeared in 2005, it featured a set of female pin headers exposing most of the pins of the ATmega168 for easy hacking and for connecting accessory boards known as 'Shields'. The purpose of a shield is to provide new plug-and-play functionality to the host microcontroller, such as circuit prototyping, motion control, sensor integration, network and radio communication, or gaming interfaces, without worrying too much about the hardware implementation details. Seven years after the birth of the original Arduino, new shields keep coming out and are being cataloged on http://shieldlist.org/, a testament to the versatility of the design. It is also simple to build a DIY shield when nothing out there will meet your needs or when you want to understand how the shield concept works from the ground up.

In their infinite wisdom, Secret Labs, the makers of the Netduino, adopted the same Arduino form factor and header pin out to let .NET Micro Framework users tap into the vast array of Arduino shields on the market. Yet, there's always one hurdle that needs to be overcome: in order to give access to their hardware functions easily, many Arduino shields provide sample sketches (a.k.a. C/C++ Wiring programs) and libraries also written in C/C++ designed to be used within the Arduino IDE. Unfortunately, Arduino sketches and libraries aren't compatible with the Visual Studio environment and the .NET runtime: they need to be adapted in order to make use of the shield's hardware.

The goal of this series of articles is to attempt to demystify what an Arduino shield is. To do this, we'll start by building one from scratch. Then, we'll present a generic approach for selecting Netduino-compatible Arduino shields and adapting Arduino code to interface with the .NET Micro Framework.

Selecting Arduino shields for use with Netduino / Plus

Arduino shields using hardware components interfaced over protocols such as SPI, I2C, 1-Wire or serially over a UART are generally good candidates for a Netduino adaptation because the .NET Micro Framework supports these protocols natively and can do bulk I/O transfers, yielding good performance.

However, if a shield requires bit-banging data on GPIOs (i.e. communicating data serially, such as SPI, I2C, RS-232, in software by toggling GPIO lines individually instead of using dedicated hardware interfaces) or has very low I/O latency requirements, it may not be practical or even possible to use the shield on a Netduino / Plus.

The reason for this is simple: the Arduino runs native code and can access hardware registers directly with a latency orders of magnitude lower than what the .NET Micro Framework can achieve on a Netduino / Plus where toggling GPIOs means going through multiple framework layers while running interpreted code. The maximum raw I/O toggling frequency on a Netduino / Plus clocked at 48 MHz was measured around ~8.4KHz which is slow compared to the few MHz achievable on an Arduino clocked at 16 MHz.

Fortunately, there are possible workarounds and strategies

  • Whenever an Arduino library bit-bangs SPI data on GPIOs, regardless of the pins used to do it, it can be replaced by using the standard SPI interface on the Netduino / Plus.
  • The Netduino / Plus has significantly more RAM available than the Arduino and can transfer larger SPI data buffer in a single shot, dramatically reducing I/O latency. For instance, driving a display shield would greatly benefit from this method where a frame is cached in RAM on the Netduino / Plus then sent in one shot over SPI to the hardware display driver.

The bottom line is that it is always a good idea to review how the Arduino code interfaces with a given shield before proceeding with a purchase or starting a conversion project. This review process is also facilitated by http://shieldlist.org which shows which pins are being used to drive a shield. For example, the Adafruit Industries Logger Shield uses hardware SPI (pins D10-D13) for the SD card and I2C (pins A4-A5) for the DS1307 real time clock, making it a perfect adaptation candidate for the Netduino / Plus as we'll see in our next article.

imageimage

It's also very important to know what features are available on the .NET Micro Framework running on the Netduino / Plus: some things come standard with the .NET Micro Framework which normally require add-ons libraries on the Arduino such as file system and networking support.

Finally, it is wise to search code repositories such as CodePlex, BitBucket and GitHub for hardware drivers and libraries before undertaking writing one in C# from scratch based on component datasheets. This extends to the Netduino and the TinyCLR community forums where many people have posted drivers in discussion threads.

Building a shield from scratch to meet specific requirements

Recently, we were asked if it was possible to connect our Touch Display module designed for a Netduino Go! to a Netduino / Plus. By doing a bit of research and seeing how the driver for the Touch Module works, this can be done by building a simple custom shield composed of a few parts connecting the Netduino pin headers to a Netduino Go! socket breakout board like so:

FinishedCustomShieldGoTouchDisplayOnNetduino

High-Level Software Interface

To frame the rest of this article, the communication interface with the shield is done using SPI and a GPIO used for synchronization. The communication protocol details are wrapped in the Nwazet.Go.Display.Imaging.VirtualCanvas class which needs to be initialized with the SPI and GPIO parameters matching the pin out of the shield:

var canvas = new VirtualCanvas(TouchEventHandler, WidgetClickedHandler);

canvas.Initialize(
    displaySpi: SPI.SPI_module.SPI1,
    displayChipSelect: Pins.GPIO_PIN_D9,
    displayGPIO: Pins.GPIO_PIN_D8,
    speedKHz: 5000);

From that point on, all interactions with the shield are done through Draw* methods followed by a call to the Execute() method which handles sending and receiving SPI data packets. The VirtualCanvas class also provides methods for creating widgets such as buttons, receiving touch screen events and setting the screen orientation.

For example, the following code snippet draws and updates a progress bar and uses one of the proportional fonts built into the display:

public static void Main() {
    var canvas = new VirtualCanvas();
    canvas.Initialize(
        displaySpi: SPI.SPI_module.SPI1,
        displayChipSelect: Pins.GPIO_PIN_D9,
        displayGPIO: Pins.GPIO_PIN_D8,
        speedKHz: 5000);
    var fontInfo = new DejaVuSans9().GetFontInfo();
    canvas.DrawFill(0xFFFF);
    canvas.DrawString(5, 144, (ushort)BasicColor.Black, fontInfo.ID, "Progress");
    for (var progress = 1; progress <= 100; progress++) {
        canvas.DrawProgressBar(
            70, 140,
            75, 12,
            RoundedCornerStyle.All,
            RoundedCornerStyle.All,
            (ushort)BasicColor.Black,
            (ushort)GrayScaleValues.Gray_128,
            (ushort)GrayScaleValues.Gray_30,
            (ushort)BasicColor.Green,
            progress);
        Thread.Sleep(100);
        canvas.Execute();
    }
}
Netduino Go! Socket Pin Out

In order to build the shield, we need to start with mapping out the connections between the Go! bus socket and the header pins of the shield.

The Go! socket pin out was designed by Secret Labs to be compatible with Gadgeteer modules supporting the following socket types: S (SPI), U (UART), X (3 GPIO) as documented in the .NET Gadgeteer Mainboard Builder's Guide v 1.8, page 6. This makes our little shield compatible with a Gadgeteer board as long as it is connected to an S socket. As far as other .NET Micro Framework boards are concerned, they should also work fine if they can drive an SPI slave device at 5 MHz, the minimum SPI clock frequency required by the Touch Display module.

Gadgeteer Socket Types

image

Netduino Go! Socket

image

The hardware specifications of the Netduino / Plus tells us that the Netduino GPIOs correspond exactly to the Arduino Uno GPIOs:

  • digital pins 0-1: UART 1 RX, TX
  • digital pins 2-3: UART 2 RX, TX
  • digital pins 5-6: PWM, PWM
  • digital pins 7-8: UART 2 RTS, CTS
  • digital pins 9-10: PWM, PWM
  • digital pins 11-13: SPI MOSI, MISO, SPCK
  • analog pins 4-5: I2C SDA, SCL

With this information, we can proceed with the creation of schematics to bridge the gap between the two worlds.

Shield schematics

What is a shield schematics

How does this custom shield work?

The Netduino Go! bus is designed around the SPI protocol (see Go! socket pins 6-10) which the Netduino / Plus can speak easily, making a Netduino Go! module or a S-type Gadgeteer module appear like any other SPI device to a Netduino / Plus.

You will notice that the following pins aren't connected on the Go! socket for the sake of simplification:

  • Pin 2 (5v power): the Touch Display module operates on 3.3v, therefore the 5v power supply is not needed but could be connected to the 5v header of the Netduino to be fully compliant.
  • Pin 4 and 5 (UART): the Touch Display module does not make use of the serial interface during normal operation, so these lines can remain disconnected. However, to be fully compliant, Pin 4 (RX) and 5 (TX) on the Go! socket could be respectively connected to Netduino pin D1 (TX) and D0 (RX).
  • The fact that these lines aren't connected in this specific scenario would cause another module requiring a UART and/or 5v to not work obviously.

While the SPI part is straight forward, there's a bit more to the Go! bus electrical specification that must be taken into account: the Netduino Go! bus also uses its GPIO pin on boot (see Go! socket pin 3) to control the behavior of modules based on ARM Cortex chips: when the GPIO pin is held HIGH on module power-up, the ARM Cortex chip enters its bootloader mode and waits to be flashed with new firmware over the Go! bus UART (see Go! socket pins 4-5). The ARM Cortex bootloader remains active until the ARM Cortex chip is reset or power-cycled.

This is important to know for two reasons:

  1. The Touch Display module is powered by an ARM Cortex M3 chip.
  2. On boot, a Netduino / Plus sets all of its I/O pins HIGH, preventing the Touch Display from booting its firmware, which is undesirable. The reason for the I/O pins being set HIGH is documented on page 5 of the ATMEL AT91SAM7X datasheet which states that the pins on Parallel IO Controller A and B (PA0 - PA30 and PB0 - PB30) are pulled-up input at reset. The pins stay in that HIGH state until they're reconfigured by the Tiny CLR and the C# application itself.

clip_image002

For this reason, the custom shield is designed to control the power supply of the Touch Display module through a general-purpose 2N4403 PNP transistor (see T1_PNP on the shield schematics) connected to pin D7: it is only when the base of the transistor is asserted LOW that power flows to the Touch Display module, countering the behavior of the Netduino / Plus on boot. In addition, the Netduino / Plus controls the state of the Go! bus GPIO pin through D8, asserting it LOW before powering up the Touch Display module.

About the 2N4403 transistor: any other PNP transistor, or a P-Channel MOSFET, capable of switching at least 150mA continuously, the maximum current consumption of the touch display with some headroom, would have worked equally as well. The 2N4403 used here is more than adequate:

image

In the context of this shield, the PNP transistor is used as a switch, either fully ON or OFF, as opposed to being used as an amplifier. To this end, a 1K ohm resistor is used between the base of the transistor and Netduino / Plus pin D7 (POWER_CTRL) to ensure that the transistor is fully saturated but also limiting the maximum current sunken through pin D7 and potential damage being done to the ATMEL chip. The 10K ohm pull-up resistor placed between the base of the transistor and the 3.3v power rail ensures that the transistor will always be turned off by default, even when pin D7 is floating (i.e. not specifically declared as an Input or as an Output and driven HIGH or LOW by the C# application).

The PowerUpDisplay function summarizes the interaction with the module through the shield on boot:

// Pin connected to the transistor controlling the display's power supply
public static OutputPort PowerTransistor = new OutputPort(Pins.GPIO_PIN_D7, true);

public static void PowerUpDisplay() {
    // Ensure that the GPIO pin in low to prevent the display module to start in bootloader mode
    var goBusGPIO = new OutputPort(Pins.GPIO_PIN_D8, false);
    // Power up the display module
    PowerTransistor.Write(false);
    // Always wait 250ms after power-up to ensure that the display module is fully initialized before sending commands
    Thread.Sleep(250);
    goBusGPIO.Dispose();
}

Refactoring a Netduino Go! C# driver to work on a regular Netduino / Plus

The final step to get the Touch Display module working outside of its natural environment involved refactoring its C# driver (VirtualCanvas.cs), eliminating the idiosyncrasies specific to Netduino Go! bus. Go! modules are supposed to implement the GoModule interface as defined by the Netduino Go! SDK. Because the regular Netduino / Plus SDK has no knowledge of this interface, it's necessary to strip out any references and API calls specific to the Go! framework, leaving only what's absolutely required to communicate with the Touch Display module over SPI and maintaining the disposable nature of the class. For more details on Go! SDK, please refer to the Netduino Go! community forums and the source code of the existing module drivers as it is currently the best source of documentation.

This step is akin to the work required when adapting an Arduino library to run on the .Net Micro Framework, only in this case, the task is easier since we're dealing with a C# driver to begin with instead of going from C/C++ to C#.

Starting from the top of VirtualCanvas.cs, the following changes were made in the Netduino / Plus version of the driver:

  • Removed
    • using GoBus;
  • Replaced
    • public class VirtualCanvas : GoModule
    • with: public class VirtualCanvas : IDisposable
  • Replaced
    • public void Initialize(GoSocket socket, uint speedKHz = 25000)
    • with: public void Initialize(SPI.SPI_module displaySpi, Cpu.Pin displayChipSelect, Cpu.Pin displayGPIO, uint speedKHz = 25000). The core of the function simply initializes the SPI interface.
  • Replaced
    • protected override void Dispose(bool disposing)
    • with: public void Dispose() also removing the following calls:
      • SetSocketPowerState(false); this call is used by the GoModule object model to control when a socket is powered ON / OFF and is no longer applicable when the VirtualCanvas class is not derived from GoModule.
      • base.Dispose(disposing); by the same token, deriving from GoModule requires overriding the behavior of the Dispose function and calling the base class at the end, something that is no longer needed now that the class implements the regular IDisposable interface.
  • Moved
    • GoBusIrqEvent.Reset(); from WaitUntilGoBusIrqIsAsserted()
    • to: Execute(Synchronicity sync = Synchronicity.Synchronous) taking into account the higher latency of the Netduino / Plus

The rest of the code remained unchanged. The Netduino / Plus Touch Display driver and test application for this custom shield can be downloaded from the Netudino Helpers project on CodePlex in the \Samples\Coding4Fun directory.

Conclusion

With nearly 300 known Arduino shields on the market, there's a wide variety of plug-and-play functionality waiting to be leveraged by the Netduino community, sometime with little or no software work required. When all else fails, building a shield from scratch to get a desired feature onto a Netduino / Plus is a relatively simple process only requiring reading component datasheets and some patience with a soldering iron or a small breadboard. In our next article, we'll put these guidelines to the test with a simple and popular off-the-shelf data logger shield made by Adafruit Industries.

Appendix

To build the shield interfacing with the [nwazet Touch Display, you will need the following parts:

Custom shield Eagle schematics
Bill of materials (~$15 for the shield w/o the [nwazet Touch Display module)
Eagle libraries
Netduino Go! Wiki

Bio

Fabien is the Chief Hacker and co-founder of Nwazet, a start-up company located in Redmond WA, specializing in Open Source software and embedded hardware design. Fabien's passion for technology started 30 years ago, creating video games for fun and for profit. He went on working on mainframes, industrial manufacturing systems, mobile and web applications. Before Nwazet, Fabien worked at MSFT for eight years in Windows Core Security, Windows Core Networking and Xbox. During downtime, Fabien enjoys shooting zombies and watching sci-fi.

Follow the Discussion

Remove this comment

Remove this thread

close

Conversation Locked

This conversation has been locked by the site admins. No new comments can be made.