Introduction

In our previous article, we examined what an Arduino shield is, how to build a simple custom shield and discussed how to quickly identify shields that are good candidates for a Netduino adaptation versus shields that may not be.

In this article, we’ll take a popular Arduino Logger Shield produced by Adafruit and we’ll interface it with a Netduino / Plus microcontroller

The Arduino Logger Shield is an excellent one to start with because it offers immediate benefits to a Netduino / Plus user:

• Time-keeping
• SD card storage
• Two user-controllable LEDs
• A small prototyping area
• An onboard 3.3v voltage regulator for clean analog readings and power decoupling

In our C# data logging application, we'll interact with the time keeper, the SD card storage and its 'card detect' pin, the two LEDs as well as a temperature sensor (not included with the shield).

Before diving into the details associated with the hardware, you may want to take a look at the C# objects representing the hardware:

public static readonly string SdMountPoint = "SD";
public static OutputPort LedRed = new OutputPort(Pins.GPIO_PIN_D0, false);
public static OutputPort LedGreen = new OutputPort(Pins.GPIO_PIN_D1, false);
public static InputPort CardDetect = new InputPort(Pins.GPIO_PIN_D3, true, Port.ResistorMode.PullUp);
public static readonly Cpu.Pin ThermoCoupleChipSelect = Pins.GPIO_PIN_D2;
public static DS1307 Clock;
public static Max6675 ThermoCouple;

and their initialization:

public static void InitializePeripherals() {
    LedGreen.Write(true);
    Clock = new DS1307();
    ThermoCouple = new Max6675();
    InitializeStorage(true);
    InitializeClock(new DateTime(2012, 06, 14, 17, 00, 00));
    ThermoCouple.Initialize(ThermoCoupleChipSelect);
    TemperatureSampler = new Timer(new TimerCallback(LogTemperature), null, 250, TemperatureLoggerPeriod);
    LedGreen.Write(false);
}

The SD card, represented by the SdMountPoint string, communicates with the application over SPI. The presence of the SD card in the reader is determined through the CardDetect input pin.

The LEDs are simple outputs that we'll turn ON / OFF as the peripherals gets initialized and file I/Os take place with the SD card.

The clock communicates with the application over the I2C protocol. The clock's most important functions are accessed through the Set() and Get() methods respectively used to set the time once and to get updated time stamps afterward.

The thermocouple communicates over SPI with the application. It exposes a Read() method which caches a raw temperature sample accessed through the Celsius and Fahrenheit properties.

Note: the Netduino Plus already features a built-in microSD card reader, in which case, having another one on the shield is not really needed. Except for this hardware difference, everything else discussed within this article applies equally to the regular Netduino and the Netduino Plus.

Interfacing with the Arduino Logger shield’s hardware

Adafruit is pretty good about making usable products and generally provides Arduino libraries to use with their hardware. Indeed, the Arduino Logger Shield is well documented and comes with two C++ libraries: SD which implements a FAT file system and supporting low-level SD card I/O functions. RTCLib which wraps the I2C interface required to communicate with the DS1307 real time clock.

The SD Card Interface

Let’s deal with the SD card reader and the file system first: a quick review of SD.h reveals two C++ classes:

• class File : public Stream {} exposing standard read, write, seek, flush file access functions.
• class SDClass {} exposing storage management such as file and directory operations.

This is good news because the .NET Micro Framework on the Netduino already supports file streams and directory management through the use of the .NET MF System.IO assembly. This assembly comes with the .NET MF SDK port to the Netduino.

By the same token, interfacing with an SD card is provided by an assembly built by Secret Labs named SecretLabs.NETMF.IO which comes with the Netduino SDK.

SecretLabs.NETMF.IO provides two functions for 'mounting' and 'un-mounting' an SD card device and the associated FAT file system so that it can be made usable by the .NET MF through assemblies such as System.IO.

It's important to note that the SecretLabs.NETMF.IO assembly must not be deployed with an application targeting the Netduino Plus: on boot, the .NET Micro Framework implementation specific to the Netduino Plus automatically detects and mounts the SD card if one is present in its microSD card reader. This functionality is redundant with the MountSD / Unmount functions provided by the SecretLabs.NETMF.IO assembly which is only needed on Netduino SKUs without a built-in SD card reader.

How does the .NET MF interact with the SD card through the shield?

At this point, it's a good time to review the Arduino Logger Shield's pin-out and the shield's schematics:

As we know from our previous article, pins D10-D13 map to the SPI interface and pins A4-A5 map to the I2C interface of the Netduino. On the shield's schematics, the SPI interface leads us to the SD & MMC section of the diagram, connected through a 74HC125N logic-level shifter chip indicated as IC3A-D.

The role of the logic-level shifter is to ensure that logic voltages supplied to the SD card do not exceed 3.3v, even if they come from a microcontroller using 5v logic levels, such as the Arduino. When using an SD card with a Netduino, a level-shifter is not required since all logic levels run at 3.3v on the AT91SAM7x chip but it doesn't interfere with any I/O operations either when the voltage is already 3.3v.

The SD card reader in itself is just a passive connector, giving access to the controller built into the SD card. It also provides a mechanical means (i.e. switches) of detecting the presence of a card in the reader (see JP14 pin 1) as well as detecting if the card is write-protected (see JP14 pin 2). We'll make use of the card detection pin in the sample temperature logging application later on.

For background on how SD cards work, the following application note "Secure Digital Card Interface for the MSP430" is excellent and much easier to digest than the extensive 'simplified' SD card protocol specifications provided on the SD Card Association site. The following table taken from the "Secure Digital Card Interface for the MSP430" shows the pin out of an SD card and the corresponding SPI connections:

An SD standard-compliant card can support 3 distinct access modes, each one providing different performance characteristics:

• SD 1-bit protocol: synchronous serial protocol with one data line, one clock line and one line for commands. The full SD card protocol command set is supported in 1-bit mode.
• SD 4-bit protocol: this mode is nearly identical to the SD 1-bit mode, except that the data is multiplexed over 4 data lines, yielding up to 4x the performance of SD 1-bit mode. The full SD card protocol command set is supported in 4-bit mode.
• SPI mode: provide a standard SPI bus interface (/SS, MOSI, MISO, SCK). In SPI mode, the SD card only supports a subset of the full SD card protocol but it is sufficient for implementing a fully functional storage mechanism with a file system.

As you might have guessed, the .NET Micro Framework on the Netduino makes use of the SD card in SPI mode (see \DeviceCode\Drivers\BlockStorage\SD\SD_BL_driver.cpp). The block-oriented SD card I/Os are abstracted thanks to the FAT file system provided by the System.IO assembly (see \DeviceCode\Drivers\FS\FAT\FAT_FileHandle.cpp and FAT_LogicDisk.cpp).

The role of the SecretLabs.NETMF.IO assembly on the Netduino (or its built-in equivalent on the Netduino Plus) is to initialize the SD card in SPI mode during the 'mounting' process by sending the proper set of commands as defined in the SD Card protocol.

In the C# code of the AdafruitNetduinoLogger sample application, which we will review as a whole later on in the code walkthrough section, the following function takes care of the SD card initialization:

public static void InitializeStorage(bool mount) {
    try {
        if (mount == true) {
            StorageDevice.MountSD(SdMountPoint, SPI.SPI_module.SPI1, Pins.GPIO_PIN_D10);
        } else {
            StorageDevice.Unmount(SdMountPoint);
        }
    } catch (Exception e) {
        LogLine("InitializeStorage: " + e.Message);
        SignalCriticalError();
    }
}

Once mounted, the file system is accessed through System.IO calls such as this:

using (var tempLogFile = new StreamWriter(filename, true)) {
    tempLogFile.WriteLine(latestRecord);
    tempLogFile.Flush();
}

Using the StreamWriter class in this context made sense for writing strings as used in the sample application:

However, there are many other file I/O classes available in System.IO that may be better suited depending on the scenario.

The DS1307 real time clock

Our next step is to examine the interface with the DS1307 real time clock (RTC). We'll start by extracting the most important parts of the DS1307 datasheet and reviewing how it's wired up on the shield's schematics.

DS1307 features

• Real-Time Clock (RTC) Counts Seconds, Minutes, Hours, Date of the Month, Month, Day of the week, and Year with Leap-Year Compensation Valid Up to 2100
• 56-Byte, Battery-Backed, General-Purpose RAM with Unlimited Writes
• I2C Serial Interface
• Programmable Square-Wave Output Signal
• Automatic Power-Fail Detect and Switch Circuitry
• Consumes Less than 500nA in Battery-Backup Mode with Oscillator Running

Note: If you need to measure the time something takes in milliseconds, a time granularity that the DS1307 clock does not provide, you can use the Utility functions provided by the .NET Micro Framework like this:

var tickStart = Utility.GetMachineTime().Ticks;

// <...code to be timed...>

var elapsedMs = (int)((Utility.GetMachineTime().Ticks - tickStart) / TimeSpan.TicksPerMillisecond);

This timing method relies on the CPU's internal tick counter and is not 100% accurate due to the overhead of the .NET MF itself but may be sufficient in most scenarios. In addition, the internal tick counter rolls over every so often, something that should be taken into account in production code.

DS1307 register map

Accessing the clock's features comes down reading and writing to and from a set of registers as described on page 8 of the datasheet.

Page 9 of the DS1307 datasheet provides more details about the square wave generation function of the clock, which we will not be using here. The generated square wave signal is available on the shield through connector JP14 on pin 3 as you can see on the schematics below and can be used to provide a slow but reliable external clock signal to another device such as a microcontroller.

DS1307 I2C bus address

The final piece of the puzzle needed before we can use the DS1307 is the device's address on the I2C data bus and its maximum speed (specified at 100 KHz on page 10 of the datasheet). The device address is revealed on page 12 as being 1101000 binary (0x68) along with the two operations modes (Slave Receiver and Slave Transmitter) of the clock. The 8th bit of the address is used by the protocol to indicate whether a 'read' or a 'write' operation is requested.

Note: I2C devices sometime make use of 10-bit addresses. If you aren't familiar with the I2C data bus, you should read the section of the datasheet starting on page 10 which provides a good foundation for understanding how I2C generally works.

It can be summarized as follows:

• I2C is a 2-wire serial protocol with one bidirectional data line referred to as SDA and one clock line, referred to as SCL.
• The I2C bus is an open-drain bus (i.e. devices pull the bus low to create a '0' and let go of the bus to create a '1'). To achieve this, I2C requires a pull-up resistor on the SCL and SDA lines between 1.8K ohms and 10K ohms. I2C devices do not need to provide pull-ups themselves if the bus already has them.
• The I2C master (i.e. the Netduino microcontroller) always provides the clock signal, generally between 100 KHz (or lower) for standard speed devices or 400 KHz for high-speed devices. There's also a 'Fast Mode Plus' allowing for speeds up to 1MHz on devices supporting it. There can be more than one master on the bus even though this is uncommon.
• An I2C device can have a 7-bit or 10-bit address, allowing for multiple I2C devices to be used on the same bus.
• I2C read and write operations are transactions initiated by the I2C master targeting a specific device by address. Some I2C slave devices can notify their master that they need to communicate using a bus interrupt.
• A transaction is framed by 'start' and 'stop signals, with each byte transferred requiring an acknowledgement signal.

At this point, we have all the pieces needed to communicate with the RTC using I2C transactions.

Using the I2C protocol with the .NET Micro Framework

On the Arduino, the library used with the shield to communicate with the DS1307 is a C++ library called RTClib. The header of the library declares a DateTime class, similar in functionality to the standard .NET Micro Framework DateTime class provided by System in the mscorlib assembly. We'll use the standard .NET MF data type to work with the clock instead.

The next declared class is RTC_DS1307 which implements the driver for the DS1307 chip using the Wire library to wrap the I2C protocol. The .NET Micro Framework also supports the I2C protocol through to the Microsoft.SPOT.Hardware assembly. Here again, we'll use the .NET MF implementation of I2C in order to communicate with the clock. However, the I2C transaction patterns implemented by the C++ driver can still provide a useful guide for writing a C# driver for the DS1307 when you don't know where to begin just based on the datasheet.

For instance, the following functions taken from RTClib.cpp shows the call sequence used with the Wiring API to address the date and time registers of the clock:

int i = 0; //The new wire library needs to take an int when you are sending for the zero register

void RTC_DS1307::adjust(const DateTime& dt) {
    Wire.beginTransmission(DS1307_ADDRESS);
    Wire.write(i);
    Wire.write(bin2bcd(dt.second()));
    Wire.write(bin2bcd(dt.minute()));
    Wire.write(bin2bcd(dt.hour()));
    Wire.write(bin2bcd(0));
    Wire.write(bin2bcd(dt.day()));
    Wire.write(bin2bcd(dt.month()));
    Wire.write(bin2bcd(dt.year() - 2000));
    Wire.write(i);
    Wire.endTransmission();
}

DateTime RTC_DS1307::now() {
    Wire.beginTransmission(DS1307_ADDRESS);
    Wire.write(i);
    Wire.endTransmission();
    Wire.requestFrom(DS1307_ADDRESS, 7);
    uint8_t ss = bcd2bin(Wire.read() & 0x7F);
    uint8_t mm = bcd2bin(Wire.read());
    uint8_t hh = bcd2bin(Wire.read());
    Wire.read();
    uint8_t d = bcd2bin(Wire.read());
    uint8_t m = bcd2bin(Wire.read());
    uint16_t y = bcd2bin(Wire.read()) + 2000;
    return DateTime (y, m, d, hh, mm, ss);
}

The final class is RTC_Millis, a utility class converting time data into milliseconds, effectively providing the functionality of the DateTime.Millisecond property on the .NET MF.

Having assessed that the functionality of RTClib only handles date and time registers and knowing the role of the other clock registers, we can proceed with implementing a complete DS1307 C# driver, supporting the square wave and RAM functions, using the native I2C protocol support of the .NET Micro Framework.

The driver starts by defining key constants matching the clock registers according to the datasheet:

[Flags]
// Defines the frequency of the signal on the SQW interrupt pin on the clock when enabled
public enum SQWFreq { SQW_1Hz, SQW_4kHz, SQW_8kHz, SQW_32kHz, SQW_OFF };

[Flags]
// Defines the logic level on the SQW pin when the frequency is disabled
public enum SQWDisabledOutputControl { Zero, One };

// Real time clock I2C address
public const int DS1307_I2C_ADDRESS = 0x68;

// Start / End addresses of the date/time registers
public const byte DS1307_RTC_START_ADDRESS = 0x00;
public const byte DS1307_RTC_END_ADDRESS = 0x06;

// Start / End addresses of the user RAM registers
public const byte DS1307_RAM_START_ADDRESS = 0x08;
public const byte DS1307_RAM_END_ADDRESS = 0x3f;

// Square wave frequency generator register address
public const byte DS1307_SQUARE_WAVE_CTRL_REGISTER_ADDRESS = 0x07;

// Start / End addresses of the user RAM registers
public const byte DS1307_RAM_START_ADDRESS = 0x08;
public const byte DS1307_RAM_END_ADDRESS = 0x3f;

// Total size of the user RAM block
public const byte DS1307_RAM_SIZE = 56;

Next the driver defines an I2C device object representing the clock:

// Instance of the I2C clock
protected I2CDevice Clock;

In the class constructor, the I2C clock device is initialized, specifying its address and speed in KHz:

public DS1307(int timeoutMs = 30, int clockRateKHz = 50) {
    TimeOutMs = timeoutMs;
    ClockRateKHz = clockRateKHz;
    Clock = new I2CDevice(new I2CDevice.Configuration(DS1307_I2C_ADDRESS, ClockRateKHz));
}

The driver retrieves the date and time from the clock through a Get function returning a DateTime object.

public DateTime Get() {
    byte[] clockData = new byte [7];

    // Read time registers (7 bytes from DS1307_RTC_START_ADDRESS)
    var transaction = new I2CDevice.I2CTransaction[] {
    I2CDevice.CreateWriteTransaction(new byte[] {DS1307_RTC_START_ADDRESS}),
        I2CDevice.CreateReadTransaction(clockData)
    };

    if (Clock.Execute(transaction, TimeOutMs) == 0) {
        throw new Exception("I2C transaction failed");
    }

    return new DateTime(
        BcdToDec(clockData[6]) + 2000, // year
        BcdToDec(clockData[5]), // month
        BcdToDec(clockData[4]), // day
        BcdToDec(clockData[2] & 0x3f), // hours over 24 hours
        BcdToDec(clockData[1]), // minutes
        BcdToDec(clockData[0] & 0x7f) // seconds
    );
}

Let's break it down:

• A 7-byte array is allocated which will receive the raw date and time data registers, starting at address DS1307_RTC_START_ADDRESS (0x00) and ending at DS1307_RTC_END_ADDRESS (0x06).
• An I2C transaction object is allocated, comprising two parameters:
  • A 'write' transaction object telling the DS1307 device which register address to start reading data from. In this case, this is DS1307_RTC_START_ADDRESS (0x00), the very first time-keeping register.
  • A 'read' transaction object specifying where the clock's time-keeping data registers will be stored, implicitly defining the total number of bytes to be read and acknowledged.
• Clock.Execute is the function calling into the .NET MF I2C interface to run the prepared transactions. The second parameter specifies a time out value expressed in milliseconds before the transaction fails, resulting in a generic exception being thrown.
• When the transactions succeed, a DateTime object is instantiated with the 7 time-keeping registers returned by the 'read' transaction. Each register is converted from Binary Coded Decimal form to decimal form using a custom utility function:

protected int BcdToDec(int val) {
    return ((val / 16 * 10) + (val % 16));
}

Conversely, the driver provides a Set function to update the clock's time-keeping registers. Because the driver doesn't expect a response from the DS1307 in this scenario, the I2C transaction is write-only. The fields of the DateTime parameter corresponding to the time -keeping registers are converted from decimal form to BCD form and stuffed in a 7-byte array before executing the transaction.

public void Set(DateTime dt) {
    var transaction = new I2CDevice.I2CWriteTransaction[] {
        I2CDevice.CreateWriteTransaction(new byte[] {
            DS1307_RTC_START_ADDRESS,
            DecToBcd(dt.Second),
            DecToBcd(dt.Minute),
            DecToBcd(dt.Hour),
            DecToBcd((int)dt.DayOfWeek),
            DecToBcd(dt.Day),
            DecToBcd(dt.Month),
        DecToBcd(dt.Year - 2000)} )
    };

    if (Clock.Execute(transaction, TimeOutMs) == 0) {
        throw new Exception("I2C write transaction failed");
    }
}

The rest of the functions provided by the C# driver implement the other DS1307 features, such as

• SetSquareWave
• Halt
• SetRAM
• GetRAM
• The [] operator used to access a specific clock register
• WriteRegister

In all case, these functions are wrappers around the 'read' and 'write' I2C transaction model, involving the appropriate DS1307 registers as defined in the datasheet. 

Using the Adafruit Arduino Logger Shield as a temperature logger

To illustrate the points discussed so far, we'll use the Adafruit Arduino Logger shield with a Netduino and a MAX6675 thermocouple amplifier for the purpose of recording ambient temperature samples at ten second intervals.

Each record includes a date, a time and the temperature expressed in Celsius and Fahrenheit. The records are written to daily files in CSV format for easy export to a spreadsheet, making the application easily adaptable for acquiring data from different sensors:

Device Connections

Instead of permanently soldering the temperature sensor to the prototyping area of the shield, female / female jumper wires were used to make connections between the shield's own pin headers as well as the thermocouple's male pin headers.

The following table enumerates these connections:

Reading temperature using an Adafruit Max6675 Thermocouple amplifier breakout board

The Max6675 thermocouple amplifier chip on the breakout board is a read-only SPI device. When the CS pin (SPI /SS) of the device is asserted with a 1ms delay before reading, the chip returns a 12-bit value on its DO pin (SPI MISO) corresponding to the temperature measured by a K-type Thermocouple wire. The resulting C# driver for the Max6675 is short:

using System;
using Microsoft.SPOT;
using Microsoft.SPOT.Hardware;

namespace Maxim.Temperature{
    public class Max6675 : IDisposable {
        protected SPI Spi;

        public void Initialize(Cpu.Pin chipSelect) {
            Spi = new SPI(
            new SPI.Configuration(
            chipSelect, false, 1, 0, false, true, 2000, SPI.SPI_module.SPI1)
            );
        }

        public double Celsius {
            get { return RawSensorValue * 0.25; }
        }

        public double Farenheit {
            get { return ((Celsius * 9.0) / 5.0) + 32; }
        }

        protected UInt16 RawSensorValue;
        protected byte[] ReadBuffer = new byte[2];
        protected byte[] WriteBuffer = new byte[2];

        public void Read() {
            RawSensorValue = 0;
            Spi.WriteRead(WriteBuffer, ReadBuffer);
            RawSensorValue |= ReadBuffer[0];
            RawSensorValue <<= 8;
            RawSensorValue |= ReadBuffer[1];

            if ((RawSensorValue & 0x4) == 1) {
                throw new ApplicationException("No thermocouple attached.");
            }

            RawSensorValue >>= 3;
        }

        public void Dispose() {
            Spi.Dispose();
        }

        ~Max6675() {
            Dispose();
        }
    }
}

Temperature logger application walkthrough

Let's review the key parts of the temperature logging application code and how it interacts with the devices connected to the shield.

public static readonly string SdMountPoint = "SD";

Defines an arbitrary string used to refer to the SD card when using StorageDevice.MountSD and StorageDevice.Unmount functions.

public static readonly int TemperatureLoggerPeriod = 10 * 1000; // milliseconds

Defines the interval between temperature samples.

public static OutputPort LedRed = new OutputPort(Pins.GPIO_PIN_D0, false);

Defines an output connected to pin D0 controlling the state of the red LED on the shield.

public static OutputPort LedGreen = new OutputPort(Pins.GPIO_PIN_D1, false);

Defines an output connected to pin D1 controlling the state of the green LED on the shield.

public static InputPort CardDetect = new InputPort(
    Pins.GPIO_PIN_D3,
    true,
    Port.ResistorMode.PullUp);

Defines an input connected to pin D3 used to determine if an SD card is inserted in the SD socket.

public static ManualResetEvent ResetPeripherals = new ManualResetEvent(false);

Defines a manual reset event object that will be used in the main application loop to determine when to re-initialize the shield's peripherals.

public static readonly Cpu.Pin ThermoCoupleChipSelect = Pins.GPIO_PIN_D2;

Defines D2 as the SPI chip select pin connected to the Max6675 Thermocouple board.

public static Timer TemperatureSampler;

Defines an instance of a timer object which will drive temperature sampling.

public static DS1307 Clock;

Defines an instance of the DS1307 real time clock driver.

public static Max6675 ThermoCouple;

Defines an instance of the Max6675 thermocouple driver.

public static ArrayList Buffer = new ArrayList();

Defines an array list instance which will be used as a temporary buffer when the SD card is removed from its socket.

The application's main loop is only concerned about the state of the peripherals:

• It initializes the devices connected to the shield
• It waits indefinitely for a signal indicating that a hardware error occurred
• It disposes of the current device instances and starts over

public static void Main() {
    while (true) {
        InitializePeripherals();
        ResetPeripherals.WaitOne();
        ResetPeripherals.Reset();
        DeInitializePeripherals();
    }
}

InitializePeripherals indicates that it is working by controlling the green LED on the shield. Its role is focused on object creation and initialization.

public static void InitializePeripherals() {
    LedGreen.Write(true);
    Clock = new DS1307();
    ThermoCouple = new Max6675();
    InitializeStorage(true);
    InitializeClock(new DateTime(2012, 06, 14, 17, 00, 00));
    ThermoCouple.Initialize(ThermoCoupleChipSelect);
    TemperatureSampler = new Timer(
    new TimerCallback(LogTemperature),
    null,
    250,
    TemperatureLoggerPeriod);
    LedGreen.Write(false);
}

If the initialization of a peripheral fails, the shield will quickly blink its LEDs, indefinitely:

public static void SignalCriticalError() {
    while (true) {
        LedRed.Write(true);
        LedGreen.Write(true);
        Thread.Sleep(100);
        LedRed.Write(false);
        LedGreen.Write(false);
        Thread.Sleep(100);
    }
}

The clock initialization function only sets the clock date and time when it is unable to find a file named 'clockSet.txt' on the SD card, ensuring that the initialization of the DS1307 only happens once in the InitializePeripherals function or until the file is deleted.

public static void InitializeClock(DateTime dateTime) {
    var clockSetIndicator = SdMountPoint + @"\clockSet.txt";

    try {
        if (File.Exists(clockSetIndicator) == false) {
            Clock.Set(dateTime);
            Clock.Halt(false);
            File.Create(clockSetIndicator);
        }
    } catch (Exception e) {
        LogLine("InitializeClock: " + e.Message);
        SignalCriticalError();
    }
}

The LogTemperature function is the callback invoked by the Timer object every 10 seconds. The function indicates that it is working by turning the red LED on the shield ON and OFF.

public static void LogTemperature(object obj) {
    LedRed.Write(true);
}

The function reads the current time from the clock with Clock.Get() and takes a temperature sample with ThermoCouple.Read().

var tickStart = Utility.GetMachineTime().Ticks;
var now = Clock.Get();
ThermoCouple.Read();
var elapsedMs = (int)((Utility.GetMachineTime().Ticks - tickStart) / TimeSpan.TicksPerMillisecond);

Then, it concatenates a string containing the date, time and temperature expressed in Celsius and Fahrenheit, with each field separated by commas.

var date = AddZeroPrefix(now.Year) + "/" + AddZeroPrefix(now.Month) + "/" + AddZeroPrefix(now.Day);
var time = AddZeroPrefix(now.Hour) + ":" + AddZeroPrefix(now.Minute) + ":" + AddZeroPrefix(now.Second) + ":" + AddZeroPrefix(elapsedMs);
var celsius = Shorten(ThermoCouple.Celsius.ToString());
var farenheit = Shorten(ThermoCouple.Farenheit.ToString());
var latestRecord = date + "," + time + "," + celsius + "," + farenheit;

To make the data more manageable, daily temperature files are created as needed, each one starting with the column headers expected for parsing the values in CSV format.

var filename = SdMountPoint + BuildTemperatureLogFilename(now);
if (File.Exists(filename) == false) {
    using (var tempLogFile = new StreamWriter(filename, true)) {
        tempLogFile.WriteLine("date,time,celsius,fahrenheit");
    }
}

The temperature sampling application lets the user remove the SD card from its socket so that the CSV files can be moved over to a PC for processing without losing data in the meantime. In order to do this, the application checks the state of the 'Card Detect' pin before attempting file system I/Os.

When the SD card is not present, the latest temperature record is preserved in the array list buffer until the SD card is put back in its socket. The array list data is then flushed to storage.

if (CardDetect.Read() == false) {
    using (var tempLogFile = new StreamWriter(filename, true)) {
        if (Buffer.Count != 0) {
            foreach (var bufferedLine in Buffer) {
                tempLogFile.WriteLine(bufferedLine);
            }
            Buffer.Clear();
        }
        tempLogFile.WriteLine(latestRecord);
        tempLogFile.Flush();
    }
} else {
    LogLine("No card in reader. Buffering record.");
    Buffer.Add(latestRecord);
}

The temperature logging function expects to run out of memory if the array list buffer grows too large, in which case, all the records get purged. Other memory management strategies could be used to mitigate data loss in this case. However, this depends entirely on the requirements of the data logging application and is out of scope for this discussion.

catch (OutOfMemoryException e) {
    LogLine("Memory full. Clearing buffer.");
    Buffer.Clear();
}

The temperature logging function also handles file system exceptions caused by the removal of the SD card and reacts by signaling the ResetPeripherals event. In turn, this lets the application's main loop know that the peripherals, and most specifically the SD card, need to be recycled and initialized again in order to recover from the error.

catch (IOException e) {
    LogLine("IO error. Resetting peripherals.");
    Buffer.Add(latestRecord);
    ResetPeripherals.Set();
}

Conclusion

In this article, we took a shield designed for the Arduino and learned how to critically review the Arduino code libraries supporting it, drawing parallels with features offered by the .NET Micro Framework. This process allowed us to identify areas in the Arduino code which were not necessary to port over to C# such as SD card and file system handlers. It also allowed us to see the similarities in the way the Arduino and the Netduino handle I2C communications.

Most importantly, we also learned the importance of reviewing a device's schematics and component datasheets to ensure that important features have not been omitted and potentially incorrectly implemented when considering using an unknown library: in the case of RTClib, we saw that the implementation was limited to the basic date and time functions of the DS1307, leaving out other useful features such as the clock's built-in RAM and the square wave generation functions.

In our next article, we'll take on a much more complex shield and we will learn how to analyze Arduino libraries in depth before porting them from C/C++ to C#.

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.

 
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.

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:

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

Netduino Go! Socket

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

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.

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:

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

• Custom shield

Bill of materials (~$15 for the shield w/o the [nwazet Touch Display module)

• 1 [nwazet Touch Display module
• 1 10cm FCI connection cable
• 1 Adafruit DIY shield for Arduino
• 1 ProtoAdvantage IDC Cable Breakout Board
• 1 PNP Transistor 2N4403
• 1 1K ohm resistor
• 1 10K ohm resistor
• 1 22 AWG solid core wire
• 1 0.32" diameter 60/40 rosin-core solder

Eagle libraries

• Adafruit Eagle library (Netduino shield part)
• [nwazet Eagle library (Go Socket part)

Netduino Go! Wiki

• Netduino GO! Module Builder's Guide (documents the Go! bus specifications)

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.

The other aspect of this gas water heater is that it keeps the water hot 24/7, 365 days a year whether we need it or not. In my home, we generally only need hot water in the morning between 7 and 9 AM and in the evening, from 5 to 9 PM. On weekends, our schedule is a bit whacky and we need hot water from 8 AM to 9PM.

So, 30 hours for week days + 26 hours for weekends, that’s 56 hours / week where hot water is actually needed, as opposed to 168 hours / week when the heater is just left alone. In order words, in our house, we only really need a third of the water heater energy that we normally consume.

To make matters worse, the water heater was installed in the garage by the builder and it gets pretty cold during the winter time.

Considering that ~25% of our heating bill goes into heating water, I felt compelled to stop this senseless waste.

The idea that I came up with was to design a scheduler, configured to follow our weekly hot water usage pattern and capable of lowering the water heater temperature down to a minimum during off-hours.

I wanted it to be cheap to build with easy-to-find parts and very reliable as my wife does not appreciate cold showers: I decided to use a netduino-mini micro-controller, an AdaFruit DS1307 real-time clock and a servo to adjust the temperature of the water heater.

Here’s what the end result looks like in action:

Startup sequence and Manual override sequence

The slow moving speed of the servo is intentional in the application in order to minimize wear and tear on the servo’s gears and the overall assembly.

Application Details

Walking through the application, there are some details worth noting:

The beginning of the application starts with a conditional compilation definition based on the hardware that you're targeting. Because the netduino boards have different format factors and on-board devices, pin assignments will vary.

By default, the application is targeting the mini:  

#define NETDUINO_MINI

Any other definition would target the regular netduino. I was unable to test with the netduino Plus, so there's no provision for it in the code yet.

#define NETDUINO_MINI

using System;
using System.Threading;
using System.Collections;
using Microsoft.SPOT;
using Microsoft.SPOT.Hardware;
using SecretLabs.NETMF.Hardware;
using netduino.helpers.Hardware;
using netduino.helpers.SerialUI;
using netduino.helpers.Servo;
using System.IO.Ports;

You must remember to include the proper reference to the Secret Labs assembly for the platform as well. If you don't your code might run, but expect very weird GPIO behavior

#if NETDUINO_MINI
    // You must ensure that you also have the reference set to SecretLabs.NETMF.Hardware.NetduinoMini in the project
    // You must also remove the SecretLabs.NETMF.Hardware.Netduino if it was there.
    using SecretLabs.NETMF.Hardware.NetduinoMini;
#else
    // You must ensure that you also have the reference set to SecretLabs.NETMF.Hardware.Netduino in the project
    // You must also remove the SecretLabs.NETMF.Hardware.NetduinoMini if it was there.
    using SecretLabs.NETMF.Hardware.Netduino;
#endif

Most of the core objects in the application last for the lifetime of the application, except for the SerialUserInterface object which may be recycled if a communication failure occurs.


namespace WaterHeaterController {
    public class Program {

#if NETDUINO_MINI
        private static readonly OutputPort _servoPowerEnable = new OutputPort(Pins.GPIO_PIN_16, false);
        private static readonly PushButton _pushButton = new PushButton(Pin: Pins.GPIO_PIN_17, Target: PushButtonHandler);
        private static readonly OutputPort _ledOverride = new OutputPort(Pins.GPIO_PIN_13, false);
        private static readonly OutputPort _ledServoPowerEnable = new OutputPort(Pins.GPIO_PIN_15, false); 
        private static readonly PWM _ledLowHeat = new PWM(Pins.GPIO_PIN_18);
        private static readonly PWM _ledHighHeat = new PWM(Pins.GPIO_PIN_19);
        private static readonly HS6635HBServo _servo = new HS6635HBServo(Pins.GPIO_PIN_20,minPulse: 700, centerPulse: 1600);
        private static SerialUserInterface _serialUI = new SerialUserInterface(Serial.COM2);
#else
        private static readonly OutputPort _servoPowerEnable = new OutputPort(Pins.GPIO_PIN_D3, false);
        private static readonly PushButton _pushButton = new PushButton(Pin: Pins.ONBOARD_SW1, Target: PushButtonHandler);
        private static readonly OutputPort _ledOverride = new OutputPort(Pins.GPIO_PIN_D2, false);
        private static readonly OutputPort _ledServoPowerEnable = new OutputPort(Pins.GPIO_PIN_D4, false);
        private static readonly PWM _ledLowHeat = new PWM(Pins.GPIO_PIN_D5);
        private static readonly PWM _ledHighHeat = new PWM(Pins.GPIO_PIN_D6);
        private static readonly HS6635HBServo _servo = new HS6635HBServo(Pins.GPIO_PIN_D9,minPulse: 700, centerPulse: 1600);
        private static SerialUserInterface _serialUI = new SerialUserInterface();
#endif
        private static readonly Schedule _schedule = new Schedule();
        private static readonly Status _status = new Status();
        private static readonly DS1307 _clock = new DS1307();

The following constants reference absolute servo positions expressed in degrees. Depending on the physical configuration of the servo installation (vertical, horizontal, left or right of the thermostat), you may need to change these values so that the servo moves in the correct direction.

The values below correspond to an 'upside down' servo (arm pointing downwards) placed on the left of the gas valve.

        private const uint LowHeat = 180;
private const uint Center = 100;
private const uint HighHeat = 0;

When the application starts, it attempts to detect if the real-time clock was ever configured properly.

If an exception occurs, caused by a faulty initialization of the DateTime object normally returned by _clock.Get(), a default date time is assigned to the clock and the schedule held in the user-backed memory of the clock is filled with zeros and the internal oscillator of the clock is finally started.

        private static void InitializeClock() {
            try {
                _clock.Get();
            } catch (Exception e) {
                Debug.Print("Initializating the clock with default values due to: " + e);
                byte[] ram = new byte[DS1307.DS1307_RAM_SIZE];
                _clock.Set(new DateTime(2011, 1, 1, 12, 0, 0));
                _clock.Halt(false); 
                _clock.SetRAM(ram);
            }
        }

The next step initializes the position of the servo: in an attempt to avoid sudden or harsh movements of the thermostat dial, the application expects the user to have positioned the arm of the servo manually at a 90 degree angle before powering ON the controller: with the servo arm's position centered, the call to _servo.Center() will hardly result in any motion at all.

                        InitializeClock();

            Log("\r\nWater Heater Controller v1.0\r\n"); 
            Log("Initializing...");
            LoadSchedule();

            PowerServo(true);
            Log("Centering servo");
            _servo.Center();
            Log("Setting heater on high heat by default");
            _servo.Move(Center, currentHeat);
            Log("Running...");
            PowerServo(false);

It's important to note that all calls to move the servo are prefixed with a PowerServo() call: the controller board was designed to control the 5 volt power supply to the servo through a transistor which gets activated / deactivated through that call. At the same time, an LED is turned ON / OFF indicating when the servo is moving.

To ensure that the motion of the servo is always nice and slow, preventing wear and tear on the gas valve as much as possible, _servo.Move() operates the servo with one degree increments at a time, with a short pause in between steps:

        // Slowly moves the servo from a position to another
        public void Move(uint startDegree, uint endDegree, int delay = 80) {
            if (delay <= 1) {
                delay = 10;
            }

            if (startDegree < endDegree) {
                for (var degree = startDegree; degree <= endDegree; degree++) {
                    Degree = degree;
                    Thread.Sleep(delay);
                }
            } else {
                for (var degree = startDegree; degree > endDegree; degree--) {
                    Degree = degree;
                    Thread.Sleep(delay);
                }
            }

            Release();
        }

The Degree property converts a degree value from 0 to 180 into servo 'pulses' ranging from 900 to 2100, based on the HS-6635HB specs, using a mapping function described here: http://rosettacode.org/wiki/Map_range#C.

Note that the servo's spec will not always match the actual capabilities of the servo and you may need to tweak these min / max pulse values after testing your specific servo like this:

public static void Main() {
            using (var servo = new HS6635HBServo(Pins.GPIO_PIN_D9))
            {
                servo.Center();
                servo.Move(90, 0, 25);

                while (true)
                {
                    servo.Move(0, 180, 25);
                    servo.Move(180, 0, 25);
                }
            }
        }

In my case, I discovered that degree 0 corresponds to 700 instead of 900 called by the specs.

Once the initialization completes, the main loop of the application runs indefinitely or until a command to shutdown is provided. The main job if the loop is to check time against the water heater schedule and to respond to user input events.

User interactions take place over a serial port on the netduino with all the heavy lifting performed by the SerialInterface.cs class: it makes it easy to build simple menus and gather user-input in an event-driven fashion to avoid polling the serial port.

When a menu option is recognized or a CR/LF was provided on a free-form field, a callback takes place to a method with the context required to process the user input.

The main menu of the application shows the flow:

        public static void MainMenu(SerialInputItem item) {
            var SystemStatus = new ArrayList();
            _status.Display(SystemStatus, _clock, _schedule);

            _serialUI.Stop();

            _serialUI.AddDisplayItem(Divider); 
            _serialUI.AddDisplayItem(SystemStatus);
            _serialUI.AddDisplayItem("\r\n");
            _serialUI.AddDisplayItem("Main Menu:\r\n");
            _serialUI.AddInputItem(new SerialInputItem { Option = "1", Label = ": Show Schedule", Callback = ShowSchedule });
            _serialUI.AddInputItem(new SerialInputItem { Option = "2", Label = ": Set Schedule", Callback = SetSchedule });
            _serialUI.AddInputItem(new SerialInputItem { Option = "3", Label = ": Set Clock", Callback = SetClock, Context = 0 });
            _serialUI.AddInputItem(new SerialInputItem { Option = "4", Label = ": Swith Heater ON / Resume Schedule", Callback = SwitchHeaterOn });
            _serialUI.AddInputItem(new SerialInputItem { Option = "X", Label = ": Shutdown", Callback = Shutdown });
            _serialUI.AddInputItem(new SerialInputItem { Callback = RefreshMainMenu });

            _serialUI.Go();
        }

Managing the user interface happens between 'bookend' calls to _serialUI.Stop() which disables the serial port interrupts and clear up any previously defined UI and and _serialUI.Go() which re-enables serial port interrupts and reset the state of the input buffer.

The display of text to the user is handled which successive calls to _serialUI.AddDisplayItem() which will display the text in the order where it was provided.

Defining user-input is done in the same manner, with successive calls to _serialUI.AddInputItem() which takes the following parameters:

Option: defines an entry in a list of one or more options that the user can pick from. This is an optional parameter. When omitted, the user input will be free form, in which case, there must only be one input item presented to the user at a time.

Label: a text label shown next to the Option field. This is an optional parameter. If the Option field is omitted, the Label should be provided to let the user know what kind of free-form input is format is expected. For example:

_serialUI.AddInputItem(new SerialInputItem { Label = "End Hour (00-23)?", Callback = SetSchedule, Context = 4, StoreKey = "sched.endHour" });

Callback: a mandatory delegate method to be called when the user hits the 'Enter' key. If one or more Option parameter was specified, the user will be shown a error message if he did not provide a valid input instead of calling the delegate method. Providing a Callback parameter alone allows defining a 'catch all' handler.

Context: an optional integer value used to manage state transitions when multiple successive user input steps are needed to complete a form. For example:

switch (item.Context) {
                case 0:
                    _serialUI.Store.Clear();
                    _serialUI.AddDisplayItem(Divider);
                    _serialUI.AddDisplayItem("Set Clock:\r\n");
                    _serialUI.AddInputItem(new SerialInputItem { Label = "Year (YYYY)?", Callback = SetClock, Context = 1, StoreKey = "clock.YYYY" });
                    break;
                case 1:
                    _serialUI.AddInputItem(new SerialInputItem { Label = "Month (01-12)?", Callback = SetClock, Context = 2, StoreKey = "clock.MM" });
                    break;
                case 2:
                    _serialUI.AddInputItem(new SerialInputItem { Label = "Day (01-31)?", Callback = SetClock, Context = 3, StoreKey = "clock.DD" });
                    break;
                case 3:...

StoreKey: optional parameter used to preserve the user's input in a dictionary where the StoreKey is the name of the value provided by the user.  In the above example, the call to _serialUI.Store.Clear(); ensures that the dictionary is empty before gathering the user's input.

Other things that are worth mentioning about the code: the .Net Micro Framework on the netduino is Spartan by design so that it can fit well within the constraints of the Atmel ARM 7 chip. As a result, things that many programmers may take for granted aren't always there or may only be partially supported, such as: Generics, Reflection, Serialization, dynamic AppDomains creation, etc. Therefore, one has to expect making trade-offs and accept that the code will not always be as 'pure' as it could be otherwise.

This is one of the reasons for creating the netduino.helpers library which aims to provide re-usable building blocks relevant to the netduino platform, attempting to lower the barrier to entry to embedded hardware development for folks coming from a pure software development background.

Building the Gas Water Heater Controller board

Electronic components

This Gas Water Heater controller board is built around the following:

• 1 netduino-mini
• 1 DS1307 real-time clock
• 1 HiTech HS-6635HB servo

as well as the following components:

• 1 1N4001 rectifier diode used on the ground pin of the 9V power supply
• 1 2N2222 transistor switching the power to the servo
• 1 1N4001 rectifier diode connected to the base of the transistor
• 1 300 Ohm resistor connected in series with the base of the transistor
• 4 LEDs of different colors
• 4 ~220 Ohm resistors for the LEDs
• 1 momentary switch
• 1 100 Ohm resistor (to be used with the switch)
• 1 10K resistor (to be used with the switch)
• 1 9 volt / 1A power wall-wart power supply
• 1 generic proto board
• straight and angled pin headers
• 1 barrel jack connector for the power supply

Simple Wiring Diagram

To further increase the life of the servo, I decided to control the power supply to the servo through a 2N2222A transistor. It works well because the servo doesn’t need to hold the water heater knob into place all the time: once positioned, the knob stays where it is and the servo no longer needs power to maintain its position.

The base of the transistor is connected to the ‘Servo Power Enable’ (pin 16 of the netduino mini) through a 300 Ohm resistor in series with a 1N4001 rectifier diode. The diode is there to eliminate 0.7 volts present on the pin even when it is turned off.

Here’s the thread on the netduino forums discussing the 0.7 volts issue which seems specific to the netduino mini.

To be on the safe side, I also added a 1N4001 rectifier diode on pin 23 (power ground) of the netduino mini to prevent any potential damage to the micro-controller if the power were connected backwards. I did not see such protection on the schematics of the mini.

Building the board:

The final board:

Mechanical Parts

• 2 popsicle sticks
• A spool of thin metal wire
• A thin but sturdy brass rod
• A section of rubber gasket long enough to fit around the circumference of the water heater knob. Make sure that the width of the rubber gasket doesn’t exceed the width of the knob’s hand-grip
• An adjustable metal ring
• Hand-craft a bracket the length of the popsicle stick from a thin strip of brass
• 10 zip ties
• 1 small wood board for mounting the servo

Mounting the servo on the water heater

I chose to anchor the servo to the gas pipe of the water heater, using the section of the pipe to the left of the gas valve. To do so, I cut a piece of wood from left-over hardwood flooring material to fit the lower left area of the pipe. I drilled holes on the top and left sides of the board so that it could be secured to the gas pipe using zip ties. I also drilled 4 holes to secure the servo to the board with long thin screws and locking nuts.

Connecting the servo to the control knob

• Drill two holes near the end of the popsicle sticks.
• Make sure that the thin brass rod fits easily through the holes but doesn’t have wiggle room either.
• Secure one of the popsicle sticks to the brass bracket with some tape then with the metal wire wrapped tightly around it.
• Insert the brass bracket between the rubber gasket strip and the metal ring
• Tighten the metal ring around the water heater knob.

The final assembly should feel tight and strong while turning the knob.

To secure the other popsicle stick to the arm of the servo, drill a few holes into the stick, matching the holes in the servo’s arm. Then weave the thin metal wire through the holes, then wrap the metal wire tightly around the stick and the servo’s arm. The final assembly should also be tight and strong while turning the servo’s arm.

Connect the popsicle sticks together with the brass rod and secure it by bending it carefully around the ends of the sticks. It’s easier to do this while the servo’s arm is not attached to the servo.

Finally, re-attach the arm to the servo and test the assembly by moving the servo’s arm slowly. 

The knob should turn in sync with the servo with ease:

Operation

Connect a dumb-terminal to COM2 on the netduino mini (or to COM1 on the regular netduino).

Using the serial interface:

• Set the clock’s date and time and define a schedule when the heater should turn ON.
• The schedule tracks 7 days, with 4 timeslots for each day. Each timeslot has a begin time defining when the heater should turn itself ON and an end time, defining when the heater should turn itself OFF.
• Setting a timeslot to 0 resets the timeslot and the heater stays OFF.
• Keep in mind that the heater timeslots and the clock expect to work on a 24 hour schedule.

Sample output:


[02/19/2011 19:29:40]
Water Heater Controller v1.0

[02/19/2011 19:29:40] Initializing...
[02/19/2011 19:29:40] Loading schedule
[02/19/2011 19:29:40] Centering servo
[02/19/2011 19:29:41] Setting heater on high heat by default
[02/19/2011 19:29:51] Running...
-------------------------------------------------------------
Time: Saturday, 19 February 2011 19:29:51
Heater Schedule Today: Sat [8-21] [0-0] [0-0] [0-0]
Heater Status: ON [scheduled]

Main Menu:
1 : Show Schedule
2 : Set Schedule
3 : Set Clock
4 : Swith Heater ON / Resume Schedule
X : Shutdown

[02/19/2011 19:29:52] Heater state change
[02/19/2011 19:29:52] Setting heater on high
1
-------------------------------------------------------------
Heater Weekly Schedule:

Sun [8-21] [0-0] [0-0] [0-0]
Mon [6-9] [17-21] [0-0] [0-0]
Tue [6-9] [17-21] [0-0] [0-0]
Wed [6-9] [17-21] [0-0] [0-0]
Thu [6-9] [17-21] [0-0] [0-0]
Fri [6-9] [17-21] [0-0] [0-0]
Sat [8-21] [0-0] [0-0] [0-0]

Meaning of the LEDs

• High heat LED: ON indicates that the water heater is set to high heat. 
• Low heat LED: ON indicates that the water heater is set to low heat.
• Servo Active LED: ON indicates that the servo is changing position.
• High heat override LED: ON indicates that the push button was used to override the schedule.

Starting the water heater controller the first time

Before you apply power to the board, make sure that the arm of the servo is centered (vertical position). This will ensure that the startup sequence is smooth. From there, the controller will slowly set the water heater knob on high heat before tracking to the schedule.

Cheers,

-Fabien.