Like its predecessor, the XBee Sensor is a .Net Micro Framework device, which uses an XBee wireless transceiver to post data to the Internet by way of a Python middleman.

I’m structuring the code to be more flexible, supporting a variety of sensors and logging to a variety of databases.  Personally, I’m using it to measure plant soil moisture, light levels, temperature and humidity, as described in the “Hardware Configuration” section below.

If you decide to use a different mix of sensors (as I’m sure you will), you’ll need to make a small change to the C# code, as shown in the Programmer’s Show and Tell section below.  I’m aiming for a more generic device configuration, where all  sensor devices run exactly the same code, and all sensor configuration is done through Python.

Since a new project gives me an excuse to start playing with new hardware, I’ve also switched from using the Netduino to a rival Micro Net Framework product, the FEZ Panda.

I’m not abandoning the Netduino: my own Netduino continues to perform its duties as a Plant Light Controller, and I’ll do my best to continue to support the Netduino in the XBee Sensor source code.  It’s relatively easy to switch the code between a FEZ and Netduino target.  I’ll point the code changes that are required in the Programmer’s Show and Tell section .

Also, the Python code used in this article is compatible with the Netduino Plant Light controller code from Watching the Watcher, so you can have both a Netduino Plant Light Controller and an XBee sensor reporting data to the Python code if you like, or even just the Netduino.

The FEZ Panda

The FEZ Panda is one of a line of products from GHI Electronics: Fez Mini, Panda, Panda II and Domino.  The Fez Mini is similar to the Netduino Mini — both mimic the form factor and pinout of the Basic Stamp — while the Pandas are similar to the Netduino.  The Domino is a more powerful beast, using a chipset that supports USB Host.

FEZ Panda II

Compared to the Netduino, the Pandas (both versions I and II) have a few advantages that will come in handy when acting as a remote sensor.

1. More pins: 54 digital I/Os, as opposed to the Netduino’s (and Arduino’s) 13, and 3 COM ports to the Netduino’s 2.  More analog pins would have been even better, but the Panda only has 6, same as the other platforms.

2. Native code.  This one is huge: the .Net code can invoke “unmanaged” native code, which has full access to the microprocessor’s capabilities, including microsecond-level timing.  This eliminates the Micro Net Framework’s biggest disadvantage to the Arduino.

3. Ability to store data in flash memory.  The FEZ firmware includes a class that allows .Net code read/write access to 4K of flash memory, analogous to the Arduino’s Flash library.

4. More documentation!  This one might not excite you as much as it does me (whee!), but GHI’s TinyCLR site offers a ton of documentation covering pretty much every feature of the FEZ platform and the underlying Net Micro Framework.  I’d particularly like to point out the Beginner’s Guide to .Net Micro Framework, which I feel is still the best publication of any type covering the MNF, and much of which is also applicable to the Netduino.  A Tutorials section was recently added to the TinyCLR site, which has rapidly expanded to cover a lot of very useful features, again many of them applicable to the Netduino.  (Both the Beginners Guide and the Tutorials section can be found on the TinyCLR Support page).

Back in the Netduino: A Little Help From Its Friends article, I used an Arduino as a helper to the Netduino.  It handled a couple of actions that the Netduino (and Micro Net Framework) couldn’t do: read data from the DHT11 temperature/humidity sensor and saving settings to Flash memory.  The FEZ Panda can actually do both these things itself.    Smarter than the average bear!

By the way, the difference between the Panda and Panda II is that the latter contains a micro SD card socket, and adds female headers for most of the additional digital pins, which are repositioned to be accessible even when an Arduino shield is in place.  I’m using Panda Is (currently being sold off by GHI at the ridiculously low price of $15), but everything that I’m doing in this project will also work on a Panda II.   The code will work almost unchanged – all you have to do is remove the Project Reference to FEZPanda_… and replace it with FezPandaII_…, as shown in the screenshot.

Selecting Panda II Assembly

Hardware Configuration

At this point, the XBee Sensor project is geared towards supporting analog sensors plus one particular digital sensor, the DHT11/DHT22 temperature and humidity sensor. I’m using the analog ports as moisture and light sensors, but any analog sensor that can run on 3.3V should work without code changes.

The XBee Sensors are intended to be used without displays, but when first configuring them it’s handy to connect an LCD to see what they’re doing (or failing to do). So, I added an optional “Debug LCD”, which displays the current sensor readings, as well as any Exceptions or other error messages.

I’ve written the code so that, if the LCD isn’t connected, it shrugs and keeps going.  However, if your device seems to behave erratically when the LCD is disconnected, you can disable use of the LCD by removing the DEBUG_LCD compiler flag (as shown in the Programmer’s Show And Tell section below).

You can also select the type of LCD using a compiler flag.  LCD support is basically the same as in the Netduino Plant Light Controller code, with the addition of the Adafruit i2c / SPI character LCD backpack — more details on that support are also in the Programmer’s Show And Tell section.

If you are using an LCD, you’ll probably want to add a button to D7, to toggle the backlight on or off.

Soil Moisture Sensors

The soil moisture sensors use the same approach as in the Garduino project.  I built mine from

• A pair of galvanized nails.  I think any nails will do, as long as they’re galvanized and big-assed, I’m using Tree Island Gold 4” 20d Hot Dip Galvanized nails
• 2 lengths of 20 AWG wire, long enough to go from the plant pot to the Panda
• a 10K resistor, connecting the analog in to ground

As you can see from the photo, one end of each wire is soldered to a nail, then covered with heat shrink tubing to keep it attached tight.  The other end of the wires connect to the Panda.  One wire connects directly to 3.3V, and the other other wire is split: it connects directly to an analog port, then connects through a 10K resistor to ground.

Moisture Sensor Wiring - Click to Enlarge

I found that the screw connectors on the Adafruit Wing Protoboard is ideal for this setup, since the screw connectors firmly hold the wires in place , and the protoboard layout makes it easy to add the resistor-to-ground connection.  The Adafruit board also provides 4 spare screw connectors, in the upper-right of the above photo – I used mine to provide the extra 3.3V connections required for this project.

The Garduino actually uses 5V, but 3.3V works just as well for this purpose, with similar calibration.  My oldest moisture sensor has been in service for almost 3 months now, with no apparent degradation of the nails or weird behaviour in the voltage readings.  (No electrocuted plants either – the 10K resistor ensures that the current is too low to hurt either plants or humans).

The light sensor is a garden variety (nyuk nyuk) cadium sensor that uses the exact same circuit as the moisture sensors: one wire connected to 3.3V, and the other split between an analog pin and ground through a 10K resistor.

Here is what the XBee Sensor looks like with all its accoutrements:

FEZ XBee Sensor - Up and Running

FEZ XBee Sensor - The Next Generation

Temperature/Humidity Sensor

I have the DHT11 from the A Little Help From Its Friends article connected to one of my XBee Sensor configurations, and the DHT11′s big brother, the DHT22, connected to another.

The code used to read from the 2 devices is identical – the only difference is how the .Net code parses the data to retrieve the temperature and humidity values.

As mentioned earlier, the Panda’s support for native “RLP” (Runtime Loadable Procedures) code means that it can handle the microsecond-level timing required by the DH22 and DHT11.

The RLP code that I’m using comes from this project on GHI’s TinyCLR site.  The description of the project only mentions the DHT11, but the RLP code works for the DHT22 too.

I’ve modified the code slightly to prevent an infinite loop if anything goes wrong with the communication, and added a few comments to explain why the code is doing what it’s doing. My modified version, along with a compiled .elf file and all of the files needed to build the .elf, can be downloaded from my Google Code project page.

(By the way, if you Google for the DHT11 or DHT22 datasheet, you’ll probably find a “Chinglish” version that’s awfully hard to understand.  A better datasheet can be found here: it refers to the RHT21, but that’s identical to the DHT22 as far as the communication is protocol is concerned).

The native code isn’t something that you copy and paste into Visual Studio alongside your C# code – instead, it is built using a separate piece of open source software with the charming name of Yagarto (Yet Another GNU ARM Toolchain).

An introduction to generating RLPs with Yagarto can be found in TinyCLR’s tutorial.  I’d recommend you use this more extensive tutorial instead, which covers a few small but important steps skipped by the TinyCLR tutorial.

However, if you’d rather not learn Yet Another Anything at this time, the good news is that you can just use the .elf file that is included with the source code for this article.  It should work with any DHT11 or DHT22 connected to any of the FEZ devices that use the USBizi100 chipset: Fez Mini, Panda, or Panda II.

You will have to get your own unlocking code from GHI, to paste into the Visual Studio project. It’s a quick and painless, if somewhat mystifying, process:

1. Create a MyGHI account here: http://www.tinyclr.com/register/

2. Once registered, login and click on the My Account link.

3. Click on the RLP Access Code link

4. Click the checkbox to agree to the “Technology Access Agreement” (which I assume is the whole point of this process), click Submit and your access code will be e-mailed to you.

The access code is pasted into the Visual Studio project, as shown in the Programmer’s Show and Tell section below.  The first time you run the unlock command on a FEZ device, it sets aside 10K for RLP use, then reboots.  The device remains unlocked after that, until the next time you update the firmware.

I’m not sure what exactly the unlock command does to your FEZ device, but based on my experience it’s a safe thing to try.  It doesn’t cause any instability or change the way that you debug your code.  If you decide you’d rather have the 10K back for .Net code, then you can remove RLP support by reloading the FEZ firmware.

I should point out one “gotcha” regarding the DHT11/DHT22 support, which probably applies to any RLP code that is timer-dependent.  You need to invoke the RLP subroutines from the main thread of the .Net application, not from a timer or event handler.  When I tried reading invoking the code from the timer thread that reads the other sensors, I found that the code ran slightly too slowly to keep up with the signals being sent from the DHT22 (which explains why I modified the code to break out of an infinite loop).  When invoked from the main thread, the code is rock solid – I haven’t noticed any failed readings in the weeks that I’ve been running it.

You might be wondering if RLP support is worth all the trouble.  If all you want is to support the DHT11/22, then you actually have an alternative to RLP: this TinyCLR Code project describes an alternative approach using just managed C# code and a clever hardware hack (which would probably also work with a Netduino, by the way).  However,  I really think RLP is worth learning, since it opens up support for all kinds of accessories previously off-limits to Micro Net Framework devices, such as Graphical LCDs and audio input.  For examples, do a search of “RLP” in the TinyCLR Code section.  Pretty much anything that the Arduino supports can (in theory) also be supported for Fez using RLP.

XBee

The XBee configuration at both the FEZ and Python end is the same as in the Netduino Meets World article, with one exception. The Python code will now be using the XBee in API mode, and its XBee (but not the one at the FEZ end) must therefore have its API mode enabled.

The easiest way to do this is to open a console connection to the XBee (as described in Netduino Meets World), and enter

+++
ATAP 1
ATWR

Or, if you prefer, you can use the X-CTU Windows application to turn on API mode.

X-CTU setting for API Mode

Note that the XBee address at the FEZ still needs to be hard-coded as “1”, even if you are using multiple XBee Sensors, or both XBee Sensors and a Netduino Plant Light Controller.  This isn’t a problem yet, since the FEZ/Netduino code doesn’t care what it receives, and the Python code doesn’t use the address to identify what it is receiving.  That will change in a future stage of the project

Python Middleware

The Python code has the same role as in the Watching the Watcher article: it forwards the sensor readings to a data repository on the Internet.

I’ve expanded the Python code to support 2 different repositories: Nimbits and Pachube.  I’ve also expanded the configuration file to give you a bit more control over which sensors are posted to which sites.

The Python code is compatible with the Netduino Plant Light controller that was created in my previous blog posts.

You can download the Python code and sample configuration file from my Google Code project page.  Note that I’ve renamed them to better reflect their role: SensorRelay.py.

The sample configuration file looks like this:

# Configuration file for SensorRelay.py
# ----------- General App Settings ------------
# XBEEPORT = \.COMxx <-- on some systems, Windows COM port 
#   must be specified in this format
XBEEPORT = COMxx
# USBPORT = COMyy
LOGFILENAME = SensorRelay.log
LOGDATA = False
SENDTIME = True
DEBUG = True
# -------- Sensor Settings -----------
#  - sensor line format is <Netduino Sensor ID> 
# = <Nimbits Data Point ID OR Pachube Datastream ID>
#[,Update Interval in seconds]
[Nimbits 1]
NIMBITS_SERVER = http://app.nimbits.com
NIMBITS_USERID = you@wherever.com
NIMBITS_API_KEY = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
UPDATE_INTERVAL = 300
A1 = ASensor,60
A2 = AnotherSensor
T1 = TemperatureSensor,1500
H1 = HumiditySensor
[Pachube 1]
PACHUBE_FEED_ID = nnnnn
PACHUBE_API_KEY = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
UPDATE_INTERVAL = 300
A1 = ASensor,60
A3 = AThirdSensor
T1 = TemperatureSensor
H1 = HumiditySensor

The settings are:

XBEEPORT = The serial port that the XBee is connected to.  On a Linux box, this would have a different format, like /dev/ttyUSBn.

USBPORT = The (very optional) serial port that an XBee Sensor is directly connected to.  (Technically, this would make it a FEZ USB/XBee Sensor – nice acronym!)

Note that you can use an XBEEPORT or a USBPORT, or both.  Just comment out or delete the one you aren’t using.

In the Python code in the Watching the Watcher article, I mentioned that the XBEEPORT setting could actually be set to the port of a USB-connected Netduino.  Why did I break that out to a separate USBPORT setting now?  The Python code now sends data to the XBEEPORT using the lower-level XBee API, while it still uses a generic Serial interface to a USB-connected device.

LOGFILENAME – The filename (or full path and filename) to which sensor data is logged in CSV format.  Note that, unlike the Python code in the Watching the Watcher article, errors and debug messages aren’t written to this file – they are written to a file named SensorRelayError.log instead, in the directory from which SensorRelay.py is run.

LOGDATA – This is used to enable or disable the logging of data to LOGFILENAME.   If your Python code is running on a ultra low power device like the Beagleboard, with just an SD card as its disk drive, then turning off data logging saves some wear-and-tear on the SD card.

SENDTIME – If true, the date and time will be sent to the XBeeSensor each minute.  You’ll want to leave this turned off if you’re using an XBee Sensor, but you should turn it on if you’re using the Netduino Plant Light Controller from my previous blog posts.

DEBUG – If true, debug messages will be written to both the console and the XBeeSensorError.log file.

The sensor configuration sections of the configuration file must always start with a name in square brackets, like “[Nimbits 1]”.  (The name can be whatever you like, actually, as long as you don’t use it more than once).  There must be at least 1 sensor configuration section, but you can have multiple sections if you want to send your data to multiple data repositories.

Personally, I use three: 1 for the public Nimbits app server (to test my code with the latest version of Nimbits), one for my personal Google App Server installation of Nimbits (to which I log more frequently), and one for Pachube, so that I can play around with its API too.

The Nimbits settings are identical to the ones used in the Watching the Watcher article – please see it for details.

The Pachube settings are almost the same as the Nimbits settings, but the lingo is somewhat different.  For details on getting started with Pachube, see my Tweet-A-Watt: Beyond the Twitter article

PACHUBE_FEED_ID = The numeric feed ID.  (A Pachube Feed is a group of datastreams.  A datastream is the Pachube equivalent of a Nimbits Data Point.)  If you want to send different sensor readings to different feeds, you should create multiple Pachube sections in your configuration file (e.g. [Pachube 1], [Pachube 2]).

PACHUBE_API_KEY = A Pachube API key that you’ve generated, and which has write access to your feeds.

UPDATE_INTERVAL = As with Nimbits, this determines how often the sensor data will be posted to Pachube, in seconds.  Note that Pachube has a rate limiter that depends on the type of plan you have.  Each datastream update counts as a separate API call, so if you have 5 datastreams, that is 5 API calls.

SENSOR_ID = DATASTREAM_ID[, UPDATE_INTERVAL] = Determines which sensor reading received from the XBee Sensor will be sent to which Pachube datastream, optionally overriding the default update interval.  For example

A1 = ASensor,60

…means that sensor A1 received from the XBee Sensor will be sent to Pachube Datastream ASensor, every 60 seconds.

Programmer’s Show and Tell

.Net Code

As before, you can get the .Net code from my Google Code page in either of 2 ways:

1. If you are familiar with Subversion, you use any SVN client (my favorite is TortoiseSVN) to get a copy of all the project files.  The SVN URL is https://gigamega-micro.googlecode.com/svn/trunk, and the code for this article is in the XBeeSensor article.
2. Or, download the good old .zip file from the Downloads section of the Google Code project. Here is a direct link to the code for this article.

I’m using the MicroLiquidCrystal library to add support for an i2c-connected LCD. The solution file will look for this project, and grumble if it can’t find it.  If you aren’t using an i2c LCD, you should remove the Reference to the MicroLiquidCrystal library from the project References list.  Otherwise, you’ll need to download the MicroLiquidCrystal source code and store it in the XBeeRemoteSensor solution folder..

While the .Net code is a totally separate project from the Netduino Plant Light controller, a lot of its contents will be familiar if you’ve read the Show and Tell sections of my previous blog posts.

Switching from the Netduino to the FEZ doesn’t require many changes to the code.  The underlying .Net Micro Framework codebase is 100% identical, and very little of the XBee Sensor code makes use of features that are specific to the Netduino or FEZ.  Where it does, I’ve used “#if” conditional compiler flags to include the correct code.

By the way, I’ve switched to putting compiler flags in the Project properties, as shown in the screenshot below, rather than hard-coding them with #define statements.  The default flag is “FEZ” – if you want to use a Netduino instead of a FEZ device, remove “FEZ” from the Conditional Compilation Symbols

Compiler Flags

In addition to getting the compiler flag right, the project’s References need to point to the right set of assemblies. For the FEZ Panda, use GHI’s libraries; for the Netduino, use SecretLabs’.  Your references lists should look like the one below – if you’ve got exclamation marks next to the GHIElectronics libraries, then perhaps you haven’t installed the FEZ SDK yet?  Otherwise, any problems are likely due to differences in the versions of the GHI libraries that I’m using and the ones you’re using – just delete the 3 GHI libraries from the References list, then add them back from the list on your PC.

Project References List

The compiler flags take care of the rest.  For example, the “using” statements at the top of each class ensure that the proper assemblies are being used:

#if FEZ
using GHIElectronics.NETMF.FEZ;
using GHIElectronics.NETMF.Hardware;
#if DHT22 || DHT11
using GHIElectronics.NETMF.Native;
#endif
#else
using SecretLabs.NETMF.Hardware;
using SecretLabs.NETMF.Hardware.Netduino;
#endif</pre>

Near the top of Program.cs, you’ll find the following code:

// !!!!!!!!!!!!!!!! USER MUST SET THE FOLLOWING 3 LINES!!!!!!!!!!!!!!!!!!!!!!!

const int NUM_ANALOG_SENSORS = 5; // number of analog sensors

#if FEZ

static FEZ_Pin.AnalogIn[] sensorPins = new FEZ_Pin.AnalogIn[] { FEZ_Pin.AnalogIn.An0, FEZ_Pin.AnalogIn.An1,

FEZ_Pin.AnalogIn.An2, FEZ_Pin.AnalogIn.An3, FEZ_Pin.AnalogIn.An4};

#else

static Cpu.Pin[] sensorPins = new Cpu.Pin[] { Pins.GPIO_PIN_A0, Pins.GPIO_PIN_A1, Pins.GPIO_PIN_A, Pins.GPIO_PIN_A3, Pins.GPIO_PIN_A4 };

#endif

static string[] sensorIDs = new

string[] { "M1", "M2", "M3", "M4", "L1", "T1", "H1" };

// !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

By default, this is configured for 5 analog sensors, A0 – A4, as well as a DHT22 providing temperature and humidity readings.  You’ll need to modify this to match your own configuration.  Note that, if using a DHT11 or DHT22, the 2 sensor IDs for temperature and humidity should be added to the end of the sensorIDs array.  The tags you use for sensorIDs can be anything you like, but they need to match the sensor IDs in the Python configuration file, SensorRelay.cfg.

Note that the above code uses a different syntax to reference analog pins on a FEZ device as compared to the Netduino.  This difference in syntax applies to the digital pins too.  While the pins might be in the same location on the outside, they map to very different CPU pins internally.

As mentioned earlier, I’ve added support for the Adafruit i2c/SPI Character LCD backpack.  This required very little code, since the backpack is supported by the MicroLiquidCrystal .Net library that I used in the Netduino Plant Light Controller code.

The backpack is enabled by adding MLC_I2C to the compiler flags.

There is only 1 I2C port on the FEZ devices (as with the Netduino), and the .Net Micro Framework is able to figure out which pins the i2c interface uses.  So, the i2c LCD initialization code just passes the number of rows and columns:

lcd = new clsLCD_MLC(4, 20);

Beyond that, the LCD interface is identical to the one used by parallel LCDs, as described in earlier articles about the Netduino Plant Light Controller.  One catch, though: I2C is quite slow compared to other LCD interfaces, and if you have multiple threads writing to the LCD, there is a good chance that one will interrupt another in mid-communication, causing the LCD to hang go all garbly.  To prevent this, I use the Monitor method of .Net’s Threading library:

static string lcdLock = "LockMe!";

. . .

try
{
	if (blnDisableLCD)
	{
		return;
	}

	// prevent other thread from writing to lcd at same time (mandatory for I2C LCD)
	Monitor.Enter(lcdLock);

	. . .

	for (int i = 0; i <= intLastRow; i++)
	{
		lcd.SelectLine((byte)(i + 1), true);
		lcd.WriteStringToLCD(strLCDBuffer[i]);

	}
finally
{
	Monitor.Exit(lcdLock);
}

Support for the DHT11 or DHT22 temperature/humidity sensor is enabled by adding the “DHT11″ or “DHT22″ compiler flag.  As mentioned earlier, this makes uses of the FEZ support for native RLP code.  The DHT11/DHT22 code won’t work at all if you’re using a Netduino.

All RLP code is initialized in basically the same way:

-          Call RLP.Enable

-          Call RLP.Unlock, passing it the values that you received in the e-mail.  Just copy and paste the “RLP.Unlock” statement from the e-mail into the code.

-          Load the RLP code (an ELF file) from your projects Resources section

-          Call GetProcedure for each RLP function that you want to call.

RLP.Enable();

//TODO - If your device isn't already unlocked,
//  you MUST paste YOUR ID and byte array into the code below
//RLP.Unlock();

byte[] elf_file = Resources.GetBytes(Resources.BinaryResources.dht11_rlp);
RLP.LoadELF(elf_file);

RLP.InitializeBSSRegion(elf_file);

ReadDHT = RLP.GetProcedure(elf_file, "ReadDHT");
DHTSetup = RLP.GetProcedure(elf_file, "Setup");

// We don't need this anymore
elf_file = null;
Debug.GC(true);

If the initialization succeeds, you can then call the DHTSetup function in the RLP code, passing it the pin that the DHT11 or DHT22 is connected to:

// Call setup function - use Di4 for DHT22
if (DHTSetup != null)
{
	success = DHTSetup.Invoke((int)(FEZ_Pin.Interrupt.Di4));
}
if (success == 0)
{
	Debug_WriteToLCD("DHT Setup failed!");
	DHTSetup = null; // disable use of DHT22
}
else
{
	// give DHT time to stabilize
	Thread.Sleep(1000);
}

To read the temperature and sensor data, call the ReadDHT function.  It returns a 5-byte array:

int intResult = ReadDHT.Invoke(bytArray);

Up to this point, the code used for the DHT11 and DHT22 is 100% identical.  The only difference is how the 5-byte array is processed to extract the temperature and humidity:

if ((intTotal & 255) == bytArray[4])
{

#if DHT22
	int intValues = 256 * (bytArray[2] & 0x7f) + bytArray[3];
	if ((bytArray[2] & 0x80) != 0)
	{
		intValues *= -1;
	}
	fltTemperature = intValues;
	fltTemperature /= 10;
#endif
#if DHT11
	fltTemperature = bytArray[2];
#endif

	Debug_WriteToLCD("Temp " + fltTemperature.ToString("F1"));

#if DHT22
	intValues = 256 * bytArray[0] + bytArray[1];
	fltHumidity = intValues;
	fltHumidity /= 10;
#endif
#if DHT11
	fltHumidity = bytArray[0];
#endif

	Debug_WriteToLCD("Hum " + fltHumidity.ToString("F1"));
}
else
{
	Debug_WriteToLCD("Checksum failed");
}

Python Code

The Python code is based on that described in the Watching the Watcher article, but with some notable improvements.

I’ve rewritten the logging code to follow proper Python standards.  So, instead of dumping error messages and debug information in the same file that contains the sensor data, I’m using the standard Python logging library:

logging.basicConfig(level=logging.DEBUG,

format='%(asctime)s %(levelname)s %(message)s',

filename='SensorRelayError.log')

log = logging.getLogger()

Note that you can change the level of logging, and the log file name, by changing this line of code.  For example, if you wanted to have debug messages sent just to the console, but not the log file, change logging.DEBUG to logging.ERROR.

Exception logging now follows Python standards as well, with the full stack trace being written to the log.  For example:

try:

    . . .

except:

    log.exception('Error sending to pachube, datapoint ' + dataPoint)

The resulting error message in the log includes all the fixings:

2011-09-19 17:40:06,180 ERROR Error sending to pachube,
   datapoint PlantLight1
Traceback (most recent call last):
File "SensorRelay.py", line 51, in sendToPachube
pac.put()
File "build/bdist.linux-armv7l/egg/eeml/datastream.py", line 45, in put
conn.request('PUT', self._url, self._eeml.toeeml().toxml(),
   {'X-PachubeApiKey': self._key})
File "/usr/lib/python2.6/httplib.py", line 914, in request
self._send_request(method, url, body, headers)
File "/usr/lib/python2.6/httplib.py", line 951, in _send_request
self.endheaders()
File "/usr/lib/python2.6/httplib.py", line 908, in endheaders
self._send_output()
File "/usr/lib/python2.6/httplib.py", line 780, in _send_output
self.send(msg)
File "/usr/lib/python2.6/httplib.py", line 739, in send
self.connect()
File "/usr/lib/python2.6/httplib.py", line 720, in connect
self.timeout)
File "/usr/lib/python2.6/socket.py", line 547, in create_connection
for res in getaddrinfo(host, port, 0, SOCK_STREAM):

The Xbee is no longer being treated as a generic serial interface, as it was in the Watching the Watcher article.  Instead, I’m using the Python XBee library, which reads and writes data using the XBee’s API.

To be honest, there is no great advantage to using the XBee API at this point.  I’ve found it to be quite stable – after the Python code opens the XBee port after startup, the port stays open and keeps working regardless of what’s going on at the sensor end of the connection.  The serial port interface to the XBee was just as stable. However, the API lets me send data to a specific remote sensor device, and lets me know which remote sensor device I’m receiving data from, something which will be necessary later in the project.

The code which communicates with the XBee is similar to the serial interface described in the Show and Tell section of Watching the Watcher.  The only significant difference is that I can now define a callback to activated when data is received, rather than having to poll for incoming  data:

if XBEEPORT:
    try:
        serXBee = serial.Serial(XBEEPORT, BAUDRATE, timeout=TIMEOUT)
        serXBee.close() # workaround for known problem when running on Windows
        serXBee.open()
        xbee = XBee(serXBee, callback=readXBeeData)

The callback function receives a “frame” as its parameter.  To get to the sensor data sent by the FEZ (i.e. the same data that would be received from the XBee when it is used as a serial device), just access the frame.data property.  Note that the frame has a bunch of other potentially useful properties, as shown in the code below.

def readXBeeData(frame):
    global buf
    try:
        frame_id = frame['id']
        # source address is 2-bytes binary (e.g. x00x01)
        # this also works: source_addr = struct.unpack('>h', frame['source_addr'])
        source_addr = ord(frame['source_addr'][0]) * 256 + ord(frame['source_addr'][1])
        # rssi (signal strength) is 1-byte binary
        rssi = ord(frame['rssi'])
        data = frame['rf_data']
        if DEBUG:
            print "read_frame, id=", frame_id, ", source_addr=", source_addr, ", rssi=", rssi, ", data=", data
            log.debug("read_frame, id=" + str(frame_id) + ", source_addr=" + str(source_addr) + ", rssi=" + str(rssi) + ", data=" + data)
        if frame_id == "rx":
            processXbeeData(data)

When sending data to the FEZ, you need to package the data into a frame.  I found that the syntax for doing this is surprisingly unGooglable: the Python XBee library is more commonly used to send the XBee a command (e.g. set D2 high), not a custom data string.  The trick is to format the data in a “TX” command.  Note that I’m adding an ending null to the data – this makes the Python code compatible with the Netduino Plant Light Controller code used in previous blog posts.

        if xbee:
            strData = strPrefix + ":" + strCommand
            # HACK - append null to data to make it look like serial data to the other end
            xbee.send("tx", dest_addr = 'x00x01', data=strData + 'x00')

When sending data to Pachube from Python, I originally used the python-eeml library, as described in the Tweet-A-Watt: Beyond the Twitter article.  However, that library still uses the Pachube V1 API, which was limited to numeric datastream IDs.  Since the XML EEML format contains a bunch of optional data that I’m not using, I decided to simplify things and use Python’s standard urllib2 libraryinstead:

        # Note - the following codes uses the V2 Pachube API and CSV data format
        url = 'http://api.pachube.com/v2/feeds/' + siteconfig["PACHUBE_FEED_ID"]
           + '/datastreams/' + dataPoint + '.csv?_method=put'
        # HACK round to 3 decimal places and drop trailing zeros : technically not needed, but makes Pachube output nicer looking
        data = ("%.3f" % floatValue).rstrip('0').rstrip('.')
        headers = {'X-PachubeApiKey': siteconfig["PACHUBE_API_KEY"]}
        if DEBUG:
            print url
            print data
            print headers
        req = urllib2.Request(url, data, headers)
        try:
            response = urllib2.urlopen(req)
        except urllib2.HTTPError, e:
            log.exception('Error code ' + e.code + ' sending to pachube, datapoint ' + dataPoint)
            return False
        except urllib2.URLError, e:
            log.exception('Reason code ' + e.reason + ' sending to pachube, datapoint ' + dataPoint)
            return False

Note the code adds an  “X-PachubeApiKey” setting to the HTTP header, something that isn’t well documented for the urllib2 library.

Wrapping Up

Whew, another super-sized article.  Believe it or not, it takes even longer to write than it does to read!  The upside is that I’ve had the code running for over a month now, so I can report that the FEZ XBee Sensor is a reliable platform with no[t too many] bugs.

I’m quite impressed with the FEZ Panda.  Its support for native code and for Output Compare (another Arduino feature that isn’t supported by the .Net Micro Framework) opens up a lot of new opportunities. GHI updates the firmware quite frequently – more often than Secret Labs does with Netduino – and I suspect they will be first out of the gate with support for the newly released .Net Micro Framework 4.2

Next, though, I’m going to turn my attention to the other end of the data stream, the data repositories.

 It’s been a few months now since the Netduino in this project, with the help of its Arduino cousin, learned to measure the temperature and humidity in the room.  It’s faithfully reporting this data on its LCD… I think.  Who really knows what it’s doing when I’m not around?  It might be sleeping, or watching Fox News, or doing God-knows-what with its “cousin”.

 Clearly, this situation demands a nanny cam.  But my eyes ache at the thought of reviewing hours of footage of an LCD displaying temperature and humidity data (… I think).

Fortunately, now that the Netduino is connected to the Internet, we have a better option: online data monitoring.

 The Asocial Network: Rise of the Machines

 You’ve probably read recently of a rising trend, The Internet of Things.  It is becoming increasingly easy to hook devices and sensors up to the Internet, where they can report their status, receive instructions, play Farmville, and murder us in our sleep.

 The backbone of this system is the online data repository, which records the data and allows you to view the results..  I’ve written before of two of the early entrants in the field, Pachube and Nimbits. 

In this article, I’ll be connecting the Netduino to Nimbits via a Python middleman.  As explained in my last article, I prefer this approach to a common alternative, connecting the Netduino directly to an Ethernet connection.  If you’re interested in trying that approach instead, there’s a whole book that shows you how.

 Both Pachube and Nimbits use a REST API to receive data from sensors.  In past articles, I showed the Python code I use to send Tweet-A-Watt data to Pachube and to Nimbits.  I’m using the same API here.

 My article on using Tweet-A-Watt with Nimbits also covers the process of creating an account on the Nimbits server, getting an API key, and creating Data Points.  You’ll need to do all these things in order to receive data from the Netduino.  Your Nimbits settings are saved in the Python configuration file, explained below.

Netduino Configuration

The Netduino hardware and software is unchanged from the previous stage of the project, Netduino Meets World.  You’ll need to have XBees configured at both the Netduino and Python ends of the configuration – details are in Netduino Meets World.

Well, actually, you don’t need XBees if the Netduino is located quite close to the PC that’s running Python.  This was true for the Netduino Meets World article as well, I just forgot to mention in there.  Since we’re using the XBees as a generic serial device, a USB connection will also work with no software changes needed.  I have one of my Netduino’s connected by USB to a Beagleboard XM running Python. 

You can’t use the Netduino’s USB port for this, but you can connect the pins to TTL-to-USB adapter.  One option is the 3.3V FTDI cable that I described way back in the Netduino: Time and Weather article.  A slightly cheaper option is an FTDI breakout board – I’m using this one from Sparkfun and can confirm that it works fine with the code accompanying this article.

Configuring the Python Interface

The Python code, TimeRelay.py, builds upon the foundation of the Python program used last time, TimeServer.py.  TimeServer was configured using command line switches – since there are a lot more settings now, I’ve switched to using a configuration file.  You can download the Python code and sample configuration file from my Google Code page, here.

The configuration file contains the following settings.   The ones that you have to fill in are marked in italics.

# Configuration file for TimeRelay.py
# SERIALPORT = \.COMxx <-- Windows COM port must be specified in this format
SERIALPORT = /dev/ttyUSB0
LOGFILENAME = TimeRelay.log
DEBUG = True
NIMBITS_SERVER = http://app.nimbits.com
NIMBITS_USERID = 
NIMBITS_API_KEY = 
NIMBITS_UPDATE_INTERVAL = 300
# Sensor IDs - format is <Netduino Sensor ID> = <Nimbits Data Point ID>[,Nimbits Update Interval in seconds]
H1 = PlantRoomHumidity,1800
T1 = PlantRoomTemperature

The first 3 settings correspond to the command line parameters in the program’s predecessor, as listed in the last article:

• SERIALPORT – Specifies the serial port that the XBee is connected to.  Note the unusual format of the serial port name for Windows PCs — this is required by the PySerial library.
• LOGFILENAME – The logfile has an expanded role – in addition to any error messages, it also records the data readings received from the Netduino in a comma-delimited format.  You can disable the local logging feature by leaving this setting blank (i.e. deleting “TimeRelay.log” from that line).
• DEBUG – Turns on debug messages written to the console.  This is on by default, since it is quite useful for troubleshooting.

The Nimbits settings are taken from your Nimbits account:

• NIMBITS_SERVER -  The default setting, app.nimbits.com, is the public Nimbits server.  If you don’t want to rub shoulders with the unwashed masses, you can setup your own private Nimbits server on Google App Engine – you would then enter your GAE server name here (e.g. whatever.appspot.com).  (Both Nimbits and GAE are free when used for this purpose.  I briefly described the process of setting up a Nimbits server in the “Rolling Your Own” section of my Nimbits article)
• NIMBITS_USERID – This is the Gmail address you used when creating your Nimbits account.
• NIMBITS_API_KEY – This key is e-mailed to you when you click the “Secret Key” toolbar button in your Nimbits server console. 
• NIMBITS_UPDATE_INTERVAL – This specifies how often Nimbits will be updated with the latest sensor reading.  The default is 300 seconds (i.e. 5 minutes), but you can override this for individual sensors on the sensor lines at the bottom of hte configuration file.  Note that the Netduino will send a new measurement every 60 seconds, regardless of what you configure here – the Python app will  send Nimbits an average of all the readings since the last update.

The sensor settings are used to link the sensor IDs hard-coded in the Netduino application with the Data Point Names that you created in Nimbits.  The default settings assume Data Point names of PlantRoomTemperature and PlantRoomHumidity – if you use other names (as you might if you don’t actually have a Plant Room), then fill them in on these lines of the configuration file.

Note that the settings shown above will send a new humidity reading to Nimbits every 30 minutes, while the temperature will be sent using the default interval of 5 minutes.  Feel free to change this depending on how meteorologically active your home is.

Activate Sensors

After you’ve finished updating TimeRelay.cfg, run TimeRelay.Py and watch the console.

The program will start by listing the settings it found in the configuration file, then will open the serial port and wait for something to happen.

If a Netduino running the code from the last article is powered on,  and you left the “Debug” setting turned on in the TimeRelay.cfg file, you should see a temperature and humidity reading displayed within a minute.  A message showing the REST API call that sends the data to Nimbits should be displayed in 5 minutes (or whatever interval you used in the TimeRelay.cfg file). 

Switch to your Nimbits web page, double-click on the Data Point in the left hand pane, and the Data Channels pane should update with the newly received value.  

There are a bunch of useful settings that you can experiment with in the Data Points dialog.  I use the Idle Alarm setting to tell me when something has gone wrong with Netduino/Python configuration, and the High and Low Value alert to tell me when something has gone terribly wrong with my home.

The Nimbits web page also has some nifty built-in graphing capabilities.  These have recently changed with the release of Nimbits 3.2, and will continue to evolve, so see the Nimbits web page and Nimbits blog for the latest.

Since I have a fairly large number of data points that I like to glance at from time to time, I wrote a Google Gadget to display line charts in the iGoogle page.  I also wrote a blog post describing its development.  Check it out and let me know of any new features you’d like to see. (Or feel free to take the code and add the features yourself).

Programmer’s Show and Tell

Although the Netduino code isn’t new, I haven’t previously explained in the sensor data handling.

The upload process is run on yet another timer.  This is hardcoded to occur every 60 seconds — nothing magical about that interval, and it could certainly be changed as needed.

Since we’re using the XBee as a generic serial interface, all the Netduino needs to do is write the data to the serial port.  The sensor ID is hard-coded, and each reading is ended with a CR/LF – a “crude but effective” message format. I haven’t noticed any problems with data being garbled or truncated:

// upload sensor readings once a minute
timerUploadSensors = new Timer(new TimerCallback(uploadSensorData),
 null, 60000, 60000);

. . .
private static void uploadSensorData(object data)
{
 string strReading = "";
 if (blnHumidityUpdated)
 {
  blnHumidityUpdated = false;
  // make copy of humidity reading, since it
  //    could be overwritten at any time
  strReading += "H1:" + strHumidity + "rn";
 }
 if (blnTempUpdated)
 {
  blnTempUpdated = false;
  // make copy of temperature reading, since it
  //    could be overwritten at any time
  strReading += "T1:" + strTempDHT11 + "rn";
 }
 uart.WriteToUART(strReading);
}

The Python code is a little more interesting.

First, I’ve added a workaround for a known problem with the PySerial library when running on Windows.  When PySerial tries to open the COM port it thinks that its already open – the workaround is to always close it before opening it.  Trippy but effective, and the workaround doesn’t cause problems on other OSes:

ser = serial.Serial(SERIALPORT, BAUDRATE, timeout=TIMEOUT)
ser.close() # workaround for known problem when running on Windows
ser.open()

The code which reads TimeRelay.cfg demonstrates some of Python’s file- and string-handling power.  Five lines of code is all that is required to open a file, read its contents, parse the lines, and store them in a dictionary. 

def readConfigFile():

    #global config

    for line in open(CONFIGFILE):

        if line.strip()[0] != "#": # skip comment lines

            parts = line.split("=", 1)

            if len(parts) == 2:

                config[parts[0].strip()] = parts[1].strip()

The sensor readings received from the Netduino are stored in a dictionary.  The key is the sensor ID (e.g. “T1”) and the value is a List with format:

<# of readings since last upload>,
<total of readings since last update>,
<date/time of last upload> 

Python dictionaries are cool because they can store any object as their value, and the object type can be different for different entries in the same dictionary.  Less cool is the fact that Python throws an exception if you try to read a dictionary key that doesn’t exist yet, so be sure to check to see if an earlier reading is already stored there.

 
# add this reading to the sensor's list
if sensor in sensorValues:
    sensorValues[sensor][0] = sensorValues[sensor][0] + 1
    sensorValues[sensor][1] = sensorValues[sensor][1] + float_value
    if DEBUG:
        print "found sensorValue", sensor, sensorValues[sensor]           
else:           
    sensorValues[sensor] = [1, float_value, datetime.datetime.now()]
    if DEBUG:
        print "adding new sensorValue", sensor, sensorValues[sensor] 

Note that Python isn’t too picky about variable types except when it is.  If “sensorValues[sensor][1] ”or “float_value” weren’t both floating point values, an Exception would be thrown when they are added together.

The code that sends the data to Nimbits uses the CurrentValue REST API.  This API has a dual role of writing new values and reading the most recent value, but we’re only using it to write data here.

The code starts out with a hack, to round the value to 3 decimal places before sending it. This is done for purely asthetic reasons, so that the readings displayed in the Nimbits web page look nice and tidy.  I call it a hack because rounding a number shouldn’t require this degree of string manipulation.  (Note to Pythonistas: I’m criticizing my code, not your language. Peace out.)

 
# HACK round to 3 decimal places and drop trailing zeros
#  - technically not needed, but makes Nimbits output nicer looking
stringValue = ("%.3f" % value).rstrip('0').rstrip('.') 

try:
    LogMsg(dataPoint + "," + stringValue)
    url = (NIMBITS_SERVER + "/service/currentvalue?value=" +
        stringValue + "&point=" + dataPoint.replace(" ", "+") +
   "&email=" + NIMBITS_USERID +
        "&secret=" + NIMBITS_API_KEY)

    urllib.urlopen(url)
    return True
except IOError:
    print 'Error sending to nimbits'
    print sys.exc_info()[0]

The REST API call is a 2-liner, another example of Python’s power and simplicity compared to .Net.  (Note to Microsoft Fanboys: I’m on your side. Peace out.)  The only trick is to replace spaces in the Data Point name with plus signs, this being a URL and all.

Note that it isn’t necessary to send a timestamp with the data – the CurrentValue API assumes the value has a current timestamp unless otherwise specified.  Good thing, that, since working with time zones in Python can be a nightmare.  (Note to Pythonistas: yeah, now I’m criticizing your language).

Unfortunately the Nimbits CurrentValue API doesn’t return a value to indicate whether the API call was successful, so the Python code won’t write an error message to the console or log file if something goes wrong.  My first indication that something is wrong is generally when Nimbits’ “Idle Alarm” sends me an e-mail.

 Wrapping Up

The Netduino project has admittedly become quite unwieldy, with each stage heaping on more hardware and/or software to the previous stage.    It’s unlikely that anyone but me has all of the Netduino hardware add-ons needed to make use of all the software’s features.

In the next article in the series, I’m going to switch to a slimmed-down Netduino software image for a sensor node, that consists of only a Netduino, an XBee, and a few new analog sensors.

[Updated August 7: Added "Windows Weirdness" section with workarounds for problems with pySerial on Windows]

Note: This article is an installment in a series about building a plant light controller (and beyond) on the Netduino microcontroller platform. For previous articles in the series, click here.

When last we saw it, the Netduino project was a pretty smart plant light controller but a pretty dumb clock. The main problem is that it can’t figure out the time on its own – when it’s powered on I have to manually set the time using its menu.

C’mon, Netduino, you don’t need me for that! Haven’t you heard of the Internet?

An Inconvenient Truth

Give a hoot, don't compute!

Instead of Ethernet, I decided to use an Xbee Series 1 connection to a PC acting as an intermediary, partly because I already had that configuration in place to support Tweet-A-Watt monitoring, but also because of certain advantages:

• Wired Ethernet connections aren’t practical for most parts of the home
• XBee is cheaper than Wi-Fi, especially if you plan to use multiple Netduinos in various parts of the home (which we will, once we add sensor monitoring to the mix)
• The Netduino is a relatively constrained development platform compared to a PC. So, it helps to limit the Netduino’s role to what’s required on the “front lines”, and have much of the code running on a PC acting as “command and control”. This, too, will become a bigger advantage when there are multiple Netduinos involved.

The big downside to this approach is that you’re leaving a PC powered on 24/7. That adds up to a lot of wasted electricity, considering how low its workload is going to be. Dedicating a 120W+ PC to this project is absurdly excessive – do you really want to make Al Gore cry?  (Well, yeah, me too – but you know what I mean.)

Fortunately, there are an increasing number of ultra low power devices that are capable of acting as the PC for this purpose. As long as it has a USB port, an Internet connection and can run Python, then it’s good to go.

I’ve written about the Beagleboard in the past. When running Linux and the Python script in this project, a Beagleboard XM uses about 3W (as measured by a Kill-A-Watt meter).

By comparison, my “energy efficient” 2 year old Windows PC averages about 120W. My older PC averages about 200W. Considering that it’s able to serve as a full-fledged home server, the Beagleboard is incredible, and hopefully an indication of the future direction of home PCs.

Incidentally, the Netduino/Arduino/LCD combination used in this project burns well less than 1W, so using *duinos in your home projects is definitely an energy-friendly alternative.

TonidoPlug Computer

Like the Beagleboards I’ve found the TonidoPlug to be very reliable device, and it’s just as power efficient. It’s not easy to upgrade or replace the OS, but the built-in version of Ubuntu is more than adequate for the projects I have in mind.

If you decide to go with a Beagleboard, one of my past articles covers installing Angstrom and Python, and this eLinux page is gospel if you’re installing Ubuntu.

As for the TonidoPlug, it comes with Ubuntu 9.04 (Jaunty Jack), Python 2.5, and an SSH Server out of the box. All you need to add for this project is the Python serial library and the GNU Screen utility for running the Python app in a background terminal session.

To install them, login as root through SSH, create then directory used by the apt package manager, then install a couple of packages:

mkdir -p /var/cache/apt/archives/partial
apt-get update
apt-get install python-serial
apt-get install screen

Connecting an XBee to a PC

Point-to-point communication ain’t no fun with just one point, so we’ll need to connect an XBee to both the PC and the Netduino.

At the PC end, whether you use a Beagleboard, TonidoPlug, or a full PC, you’ll need a USB adapter for the XBee.

There are many options out there. I’m using an Adafruit XBee Adapter and a USB TTL-232 cable. However, unless you happen to have a spare cable this is a relatively expensive option, since the adapter costs $10 and the cable costs $20. Other options that I’ve used are the $20 Parallax XBee Adapter, and SeeedStudio’s versatile $20 UartSBee.

Before connecting the XBee to the Netduino, you should configure the 2 XBees so that they will talk to one another.

By default, the XBee adapters are all configured as adapter 0 in PAN (network ID) 3332, and they’ll send their data to other adapter 0s. While this works fine if one XBee only sends, and the other XBee only receives, we’ll soon have the Netduino and PC chatting merrily away to one another. So, you should assign one of the XBees to have a different adapter ID (number 1 works fine), then set the other XBee’s destination address to be that same ID.

This page at Adafruit covers the 2 options for configuring an XBee: the Windows-only X-CTU program, and entering AT commands from a serial terminal.

Whichever configuration method you use, you need to change the “MY” setting on the first XBee to 1, and the the “DL” setting on the other XBee to 1.  That’s it: the other defaults are fine.

I’d recommend using the X-CTU program if you’re getting started with XBees: it’s much more user friendly and foolproof than a serial terminal.   While you are in there, you should update the firmware of the XBees, something you can’t do from a serial terminal.

If you’re hardcore about using a TonidoPlug or Beagleboard as a PC, or want to avoid running X-CTU for other reasons, than a serial terminal is the way to go.

Personally, I’ve used minicom on a Beagleboard and TonidoPlug for this. In order to talk to the XBee you’ll need to run minicom as root and change some of the default settings. Connect an XBee in its adapter to the USB port, then:

1. At the Linux command line, enter “minicom -s”.  If you plan to save your settings in a profile (a good idea), you should run as root: “sudo minicom -s”
2. Select “Serial port setup”
3. The serial port settings should be as shown in the screenshot below.  Press “E” to change the Bps to 9600, and press “F” to set Hardware Flow Control to “No”.  You might also need to change the Serial Device setting: its generally “/dev/ttyUSB0″, but if you have other USB devices connected: it might be /dev/ttyUSB1 or /dev/ttyUSB2, etc.
4. Press Enter to return to the minicom configuration menu, then select “Screen and keyboard”
5. Press “P” to turn on the Add Linefeed feature, and press “Q” to turn on Local Echo.
6. Press Enter to return to the configuration menu again.  To save these settings, choose one of the “Save setup” options.  To display the serial terminal,  select “Exit”.
7. The XBee is initially ready to receive and send data.  You’ll need to put it in command mode instead.  To enter command mode, press the “+” key 3 times (i.e. +++) but don’t press Enter.  The XBee should display OK.

Minicom settings for XBee configuration

The correct terminal commands for the first XBee are:

+++
ATMY 1
ATWR

And for the second XBee

+++
ATDL 1
ATWR

The XBee should send back “OK” after each command.

If you aren’t able to see what you are typing, try turning on Local Echo again: press Ctrl-A then Z to display the menu, then press E.

Note that the XBee will automatically (and silently) exit configuration mode if you wait too long between commands, so if you aren’t getting the OK after an AT command, try entering +++ again.

Connecting an XBee to a Netduino

The hardware connection to the Netduino is relatively simple, because the Netduino uses the same 3.3V voltage level as the XBee and the Netduino’s serial pins talk the same language as the XBee.

The only complication is that the XBee uses an usually tight spacing for its pins, just 2mm apart.  This makes it difficult to connect jumper cables to the pins, and impossible to plug the XBee into a breadboard.  Most people use a breakout board to solve this problem, such as Sparkfun’s XBee Breakout Board or Adafruit’s XBee Adapter PCB (which is the PCB used in their Adapter Kit – it functions well as a breakout board).

As shown in the photo below, I plugged the XBee into a small breadboard using an Adafruit XBee Adapter.  This makes it easy to share the Netduino’s 3.3V pin with other devices besides the XBee, and it allows you to connect an LED to some of the XBee’s pins for troubleshooting:

XBee To Netduino Connections

Running the Python Software

Once the hardware is in place, the next step is to start the Python software running.

You’ll need to have pySerial installed.  If you followed my instructions for configuring Angstrom Linux on a Beagleboard, or configuring Ubuntu on a TonidoPlug (earlier in this article), then you’re all set.  Otherwise, see the install instructions on the pySerial page.

Download the Python code from my Google Code project. Save the file to any folder on the host PC – if you are using a TonidoPlug or Beagleboard running Linux, then your home folder is fine.

If you are using Linux, you’ll probably need to run the Python code as root in order to access the serial port:

i.e.

sudo python TimeServer.py

The command line parameters for the program are all optional:

TimeServer.py [-nl] [-d] [-port xxxx]

• -nl – turns off logging.  Otherwise, any errors will be written to the current directory in a file named controller.txt.  Hopefully this file won’t get large, but turning off logging is necessary if you are running the code from a read-only directory.
• -d – turns on debug messages written to the console.
• -port – specifies the serial port that the XBee is connected to.  The default is /dev/ttyUSB0. On a TonidoPlug or Beagleboard, that should be the right port. On a Windows PC, the port will have a totally different name, such as COM3 – check Device Manager if you don’t know which one to use.  If you are using Windows, see the “Windows Weirdness” section below.

If you launch the program when connecting through SSH, you should first use the GNU Screen utility to open a virtual command prompt, and run the program from there. Otherwise, the program will stop running when you disconnect from SSH.

To run screen, just type “screen”. You’ll be brought to a new command prompt, at which you run TimeServer.py as above.

When TimeRelay is up and running, you can disconnect from your screen session by pressing CTRL-A, then D.  This leaves the Python code running in the background.   To reconnect to the screen session, enter screen –r –d.

GNU Screen is handy for running a background process like this because you can reconnect at any time, from any place, and run screen –r –d to see the current output from the TimeServer.py program.  This is really helpful for debugging, and for restarting the Python code if (heaven forbid!) it should start misbehaving.

Windows Weirdness

Running the Python code on Windows presents a couple of other complications, besides that whole “global warming melting glaciers” thing.

If Python throws an “The system cannot find the file specified” Exception when it tries to open the serial port, you may have run into the problem described on StackOverflow here. Try specifying the COM port as ”\.COMxx”

e.g.

-port \.COM10

Hey, don’t ask me — try it.

Also, opening a serial port sometimes results in an “Access denied” exception on Windows if you don’t close it before opening it.  Like I said, don’t ask me.  Since closing the serial port before opening it doesn’t seem to cause any problems, I’ve updated the Python code with this fix.

Running the Netduino Code

You can get the Netduino code in one of 2 ways:

1. If you are familiar with Subversion, you use any SVN client(my favorite is TortoiseSVN) to get a copy of all the project files.  The SVN URL is https://gigamega-micro.googlecode.com/svn/trunk. If you want the older version of the code to match one of the past articles, get the corresponding revision. (See the revision list here)
2. Or, download the good old .zip file from the Downloads section of the Google Code project. Here is a direct link to the code for this article.

If the Python program is running, then you’ll know within a minute of powering on the Netduino whether everything is working correctly: the date and time will automatically be set correctly via the XBee connection. Tah-dah!

OK, OK, maybe that wasn’t worth a Tah-dah.  But, that’s not all: the LED you connected to the XBee’s receive pin will light up once a minute. Tah-dah!

Hmm, tough audience.

About the only other change to the Netduino software this time is that I finally added a Daylight Savings Time setting to the Netduino’s menu: you can turn DST off or on in the “Date” menu. (Tah-dah!) This is used when calculating the “Sun Up” and “Sun Down” times, if you are basing the plant light timer on those times. Purists will point out that an Internet-connected Netduino shouldn’t have to rely on a manual setting to know when DST is in effect, but we’ll ignore those purists for now.

Programmer’s Show and Tell

The Python code is admittedly very simple: all the better to learn Python programming from, right?

The XBee’s serial port connection is opened during startup. If the connection can’t be opened, the program will display an error message and terminate by calling the Python sys.exit function. If you had some problems getting the serial port working earlier, you’re no doubt well acquainted with this error message.

try:
    ser = serial.Serial(SERIALPORT, BAUDRATE, timeout=TIMEOUT)
    ser.close() # workaround for known problem when running on Windows
    ser.open()
except:
    print "Unable to open serial port ", SERIALPORT, ". See ya."
    sys.exit(1)

The main loop checks whether the time has changed (just the minute, actually – we’ll let the Netduino handle the seconds). If it has, it calls the sendDateTime() function. It then sleeps for awhile before repeating the loop.

def displayTime():
    lastMin = -1
    while 1==1:
        try:
            currTime = datetime.datetime.now()
            if DEBUG:
                print "in displayTime, currTime = " + currTime.strftime("%Y-%m-%d %H:%M:%S")
            currMin = currTime.minute
            if lastMin != currMin:
                lastMin = currMin
                sendDateTime()
            time.sleep(15);
        except Exception:
            LogMsg("Error in displayTime")
            print sys.exc_info()[0]

Note that that the Exception handler is different from the one used when opening the serial port: it logs the error, displays some information about the error to the console (using the Python sys.exc_info function), then optimistically keeps going. If there was no Exception handler, any exception in this loop, or in the functions called by this loop, would cause the application to terminate.

This “log it and keep going” approach is generally frowned upon in software design, but I’d recommend it for a simple program like this that runs in the background.  You should find that this application, and Python code that communicates via XBee in general, is very low maintenance: you can just start it, then forget about it.  You can occasionally check on the code using GNU Screen or by looking at the contents of the controller.txt error log.

The sendDateTime function just converts the date and time to the format that the Netduino is expecting it, then writes it to the serial port. Note that the “ser.flush()” function is used to make sure that the data is sent right away rather than being buffered – this is literally time-sensitive data.

def sendCommand(strPrefix, strCommand):
    if ser:
        ser.write(strPrefix + ":" + strCommand + chr(0))
        ser.flush()

def sendDateTime():
    timeStr = time.strftime("%Y-%m-%d %H:%M")
    sendCommand("D", timeStr)

On the Netduino side, surprisingly little new code is required to talk to the XBee. We’re using the XBee as a serial port device, rather than making use of the XBee’s API (a more versatile option that I might explore in a future article). From the Netduino’s perspective, the XBee might be some guy sitting at a serial terminal, occasionally typing in a”set time” command. We’ve already implemented that support, back in the “Netduino: Time and Weather” article .

The XBee connection is opened during startup, using almost the exact same code as was used to open a serial connection to a PC terminal:

// last parm should be true for UART terminal (to send
//   user confirmation), but false for UART XBee
uart = new clsUART(strUARTPort, 9600, 512, false);

The event handler is the same one that was used for the PC terminal: the event is raised when our generic serial port class, clsUART, receives some data. In fact, if you’re using the SparkFun Serial LCD Kit, this event handler is still used when the Netduino receives data from the Arduino, as explained in the “A Little Help From Its Friends” article .

Sharing a serial command event handler between Arduino and the XBee works well, and is easy to implement in .Net. The Netduino doesn’t know, or need to know, who’s sending the command, and the .Net Micro framework ensures there isn’t any conflict between the 2 serial ports.

The only thing that’s changed here is that the XBee sends the date and time together in the same command:

D: 2011-07-25 18:01

So, I modified clsUART to check to see if the string is in this format, and it raises both a “date set” and “time set” event if it is.

if (strDateParts.Length == 5)
{
    intHours = Int32.Parse(strDateParts[3]);
    intMinutes = Int32.Parse(strDateParts[4]);
    intSeconds = 0;
    blnTimeSet = true;
}
...
// tell rest of application that the date has been set
raiseCommand(strCommand);
if (blnTimeSet)
{
    // raise the time event too
    raiseCommand("T:" + Program.Int_ToZeroPrefixedString(intHours, 2) + ":" + Program.Int_ToZeroPrefixedString(intMinutes, 2));
}

The event handler already knew how to handle date changes and time changes, so no code change was required there.

The only other significant change was modifying the menu to add a “Daylight Savings Time” switch. Since the menu code was designed to be easily extended – as explained in the Ordering Off the Menu article  – this required just 1 new line to the strMenuItems array:

"2-1", "Hour `HH`", "_UD-`HH`",
"2-1", "Min `mm`", "_UD-`mm`",
"2-1", "DST `DS`", "_DST", // NEW - Daylight Savings Time setting

The format looks rather cryptic, but it will make more sense if you read the “Programmer Show and Tell” section of Ordering Off the Menu.

The code in clsLCDMenu passes the “`DS`” keyword to its callback method for getting the current DST setting, and it passes the “_DST” keyword to the callback method for handling a new setting entered by the user.

For example, the code added to the setValueFromMenu() callback method for the “_DST” keyword is:

else if (menuCode == "_DST")
{
    // toggle DST
    blnUseDaylightSavingsTime = !blnUseDaylightSavingsTime;
    calculateSunriseAndSunset(DateTime.Now);
    if (blnUseDaylightSavingsTime)
    {
        SaveSettingToEEPROM(ADDR_DST, 2);
    }
    else
    {
        SaveSettingToEEPROM(ADDR_DST, 1);
    }
}

This recalculates the Sunrise and Sunset times (and updates the plant light timers if they are based on these times), then passes the new setting to the Arduino in the Sparkfun LCD Kit to save it to EEPROM.

I love it when a plan comes together!

Wrapping Up

I’ve found the XBee to be a very dependable add-on to the Netduino. I actually wrote the code used in this article back in May and have been running it continuously since then, and I’ve yet to have any cases where the XBee connection permanently drops or stops responding. In my experience, this is a big advantage over using an Ethernet connection – when the Netduino’s Ethernet connection drops it tends to stay down.

So, if the Xbee’s so great, why am I using it only to set the time?

Good question.

If you browse through the main Program.cs class in the source code, you’ll notice a new method called uploadSensorData, that I didn’t address in this article.

Stay tuned for the next step in the project, in which the Netduino talks back, and I draw together a couple of previously separate topics in my blog: the Netduino and Nimbits.

If you’ve made the switch to programming with .Net Micro Framework devices like the Netduino and GHI Panda, you inevitably find yourself asking the question: “What the heck do I do with all my Arduinos?”  They have a minimalistic IDE and no debugger to speak of.  They make lousy cat toys and anniversary gifts. (Unless you’re receiving one, that is.)  Who needs them?

Well, actually, you do. You might think that .Net’s “managed code” runtime environment is there to usher your program past the hardware, but it’s more like a bouncer protecting the hardware from your crummy code.   It’s great that your code can’t mess with the hardware, unless you intentionally want to mess with the hardware.

I ran into this problem when trying to upgrade the Light Controller’s analog temperature sensor with a digital “one-wire” sensor.  These types of temperature sensors have become quite common, and are generally much more accurate than analog sensors. While the Netduino’s firmware doesn’t officially support the one-wire standard yet (as of Version 4.1.0 Update 6), it is available in the GHI firmware, and I was planning to incorporate it into a Panda version of the Light Controller.

Unfortunately, not all “one wire” temperature sensors are created equally, and the one I have doesn’t follow the Dallas Semicondutors / Maxim 1-wire standard. It’s a Seeed Studios Temperature and Humidity Brick (now replaced by a Twig version) , both based on the DHT11/AM2302 chipset.

The interface to this standard is well documented (quite enthusiastically documented, in fact).  As demonstrated in the Arduino sample code, communicating with the chipset requires toggling a pin high-and-low at specific sequence of microseconds.

That’s microseconds, not milliseconds.  .Net MF doesn’t let you send signals at the microsecond level.  That’s dangerous, son.  Might shoot your eye out.

Wouldn’t it be nice if we could combine the productivity of managed C# code with the versatility of the Arduino’s AVR-C code library? Mush them together somehow, with solder and duct tape.  Hmmm…

Sadly, I happened to be out of duct tape, so I turned my attention to a Serial Enabled LCD Kit that I had recently bought from Sparkfun.  I was looking to replace the parallel LCD that comes with the Seeed Grove Starter Bundle with a serial LCD to free up some pins.

I hadn’t considered the upgradable firmware on this model as a big benefit – there isn’t much that you can do with an LCD beyond the basic set of commands that all serial LCDs support.  The kit actually incorporates an ATMega328 with the Arduino bootloader — a full Arduino, essentially.  The Arduino code reads the occasional LCD update command and passes it along to the LCD.  Between LCD updates, it sits about, twiddling its thumbs, waiting for something to do.  Hmmm…

Maybe we could use the Kit’s ATMega328 as an interface to the temperature sensor?  That’s so crazy, it might just work.

The Sparkfun Serial Enabled LCD Kit

And it does work.  (Most of the time, as I explain below.)

The Sparkfun Kit’s design makes it quite easy to implement this type of project.  It breaks out the standard 5 pins used by the FTDI cable (the serial-to-USB cable I previously used with the Light Sensor’s dearly departed UART interface), and also breaks out all of the Arduino pins not used by the LCD.

The LCD interface “firmware” is just a standard Arduino program, nothing weird, so it’s easy to merge in the sample code for reading the DHT11 sensor – mostly just copy and paste.

While I was at it, I also added some code to interface to the Arduino’s built-in EEPROM memory.

So, the end result is that the Plant Light Controller can now display the humidity, a more accurate temperature, and save the settings from the menu too.

Actually, the “more accurate” temperature is debatable.  The DHT11 chip always returns temperature as an integer, and always in Celcius.  It appears to truncate the actual temperature, rather than rounding it.  So, the temperature can be off by .9C, or 1.6F.  Humidity is similarly truncated to an integer.  But, hey, I’m not complaining – at $5, Seeed’s sensor is still a steal.

Pin Assignments

From the Netduino’s standpoint, not much changes from the previous installments of this project.  All communication with the Arduino goes through the same serial pins used by the LCD interface.  However, since the LCD now talks back, we need to connect a Netduino Serial Rx pin to the Serial LCD’s Kit TX pin, which is part of the FTDI breakout on the end of the backpack’s circuit board (the right end of the photo below).  My code uses Netduino’s COM2 (pins D2 and D3) for this.

Sparkfun Serial LCD and Seeed Temperature/Humidity Sensor

From the Serial Kit’s standpoint, the following pins are used:

-          The white JST plug contains the 5V, ground and RX pins, which we connect to the 5V, ground and TX (D3) pins of the Netduino

-          The TX pin at the end of the board is connected to the RX pin (D2) of the Netduino

-          The breakout pins at the bottom of the Serial Kit are used to connect to the Temperature/Humidity Sensor: specifically, the 5V, Ground and Analog 0 pins.

User Interface

Not much has changed here from the last installment of the project, either.  As shown in the photo below, I’ve used the leftover space on the Temperature row of the LCD to display the humidity instead of the Sunset time.

The number in parentheses is the temperature value from the sensor – the other temperature value is from the analog sensor, as added to the project in an earlier installment.  Which one is more accurate depends on how well your analog sensor is behaving – as mentioned, the digital sensor’s temperature can be off by 0.9C, while my analog sensor is apparently a little high.

Demonic LCD displaying strangely moderate temperature and humidity

I’ve also added a couple of new items to the “Timers” section of the menu, allowing you to disable the plant light timer.  This became necessary once I started saving the menu settings to EEPROM, since that ruined the handy Disable-the-timer-by-turning-the-gadget-off-and-on ™ feature.

Programmer Show And Tell

The Serial LCD Kit is now the 4^th LCD interface supported by the code, joining the parallel LCD, the Matrix Orbital Serial LCD, and the Sparkfun Serial Backpack.  I considered making the LCD Kit fully compatible with the Sparkfun Backpack’s command set by changing the Arduino “firmware” code.  The 2 command sets are quite similar, differing only when in the cursor positioning and backlight control commands.

However, I like the Serial LCD Kit’s API better, so I subclassed the Backpack’s clsLCD_SF class and overrode the commands that differed.

Subclassing is supported the same way in .Net Micro Framework as in the full blown .Net:

public class clsLCD_SFKit : clsLCD_SF

Overriding a class method is also done the standard C#, using the “new” keyword.  So, to replace the cursor positioning method with code that works with the LCD Kit’s firmware:

new public void SelectLine(byte intLine, bool blnClearLine)

I added some new commands to the LCD class, used to receive data from the Serial Kit’s Arduino.  Since its unlikely that the other LCDs are going to do much talking, I didn’t add these  methods to the common ILCD Interface.  Instead, when the main program wants to check to see if the LCD is of the Serial Kit variety, it uses the “is” keyword, again just like in the full .Net Framework:

if (lcd is clsLCD_SFKit)
{
// get the humidity
((clsLCD_SFKit)lcd).RequestHumidityAndTemp();

Data from the Serial Kit comes in through the Netduino’s serial RX pin, just like we used to read terminal commands through the UART interface.  So much like it, in fact, that I used the same event handler.  When a humidity reading or EEPROM setting comes back from the Serial Kit, the code raises a uart_Command event, as described  back in the Time and Weather article.

There is actually one big difference between the Serial Kit’s behaviour and the UART Telnet terminal, though.  The Telnet terminal could send us a command at any time, so an asynchronous interface using an event was necessary.  The LCD, on the other hand, sends data only when we ask for it.  It would have been possible, therefore, to read the data synchronously after we send the request, using code like the following:

public void RequestHumidityAndTemp()
{
byte[] command = new byte[2];
command[0] = CMD_SPECIAL;
command[1] = 71;
lcd.Write(command, 0, command.Length);
// give the LCD time to retrieve the data
Thread.Sleep(1000);
intBytesRead = lcd.Read(readBuffer, intBufferOffset, lcd.BytesToRead);
. . .
}

This has the advantage of making the context of the data we are reading obvious, but the disadvantage of introducing timing problems.  What if the LCD doesn’t respond fast enough, or the response isn’t received at all?  How long should we wait for the LCD to respond, and at what point does the Netduino decide that a response isn’t going to be received, and carries on?

Asynchronous communication does away with that problem.  In fact, you can unplug the LCD altogether, and the Netduino will faithfully carry on with its other duties, turning on and off the plant light.  It won’t receive any humidity readings, and its request to save menu settings won’t be performed (good luck using the menu without an LCD, by the way), but the Netduino doesn’t notice.

The downside of asynchronous communication is that data doesn’t necessarily come back when you want it.  You’ll see this when you first plug in the Netduino – although it requests the humidity from the Arduinio during startup, the response may not be received before the first “display the temperature” timer fires.  As a result, it may take another 30 seconds (the interval of the temperature timer) before the humidity is displayed.

The code I added to the Arduino to save settings to EEPROM takes advantage of the Arduino EEPROM library – the library makes it simple.  One minor twist is how to handle the very first interaction between Netduino and Arduino.  The Arduino has no idea whether it has any settings saved – it just returns whatever happens to be in the address you’ve requested.  The first time, this will be 0s.  So, all settings are saved as non-zero values: I add 1 to the values where necessary.

One other design decision worth mentioning is the issue of which settings to save, and when to save them.  I decided to save the date, but not the time, since it’s likely that the date will be unchanged, or very slightly changed, when you power the Netduino back on, but the time will almost certainly have changed, perhaps by hours.

The other downside of saving the time is that you’d have to do it every minute, putting wear and tear on the EEPROM.  It is best to write to EEPROM as little as possible: in this case, only when the user changes a setting in the menu.

Fortunately, I already had a callback method for responding to the user’s menu selections (as described in the Ordering Off the Menu article), so I added code like the following to that method.

static void setValueFromMenu(string menuCode, Int16 intValue)
{
. . .
if (menuCode == "_CELCIUS")
{
. . .
SaveSettingToEEPROM(ADDR_TEMP_FORMAT, 2); // 2 means Celcius

With Friends Like That…

This configuration actually did a good job of proving the point about unmanaged code: it’s awfully easy to crash the microcontroller when running it.

When I got things up and running, I found that the LCD would freeze at some point, generally a few hours after powering it on.  The Netduino soldiered on, faithfully turning the plant light off and on, so clearly it was the Arduino that dropped the ball.

Commenting out the code that requests the temperature and humidity reading caused the problem to go away, so whatever was going wrong involved the DHT11 interface.

The right thing to do would be to debug the Arduino’s DHT11 code, but the easy thing to do was to just “reboot” the Arduino on a regular basis.

Crude, but effective.  I’ve had this configuration running for over a month now, and it works like a charm.

The “rebooting” is done by using a transistor to turn the Arduino’s power off and on.  This requires a hardware change: instead of connecting the Sparkfun LCD Kit’s ground pin directly to the Netduino, I used a small breadboard to route the connection through a transistor.  The transistor is controlled using the D12 pin.

Specifically, the configuration I used (shown in the photo) is:

-          Collector pin of 2N2222 transistor to LCD Kit’s ground

-          Emitter pin of 2N2222 to Netduino ground

-          Base pin of 2N2222 to D12 pin of Netduino

-         Base pin of 2N2222 to ground through pushbutton – this can be used to manually boot the LCD Kit Arduino if necessary

Arduino Reset Circuit

The Arduino is powered up during the Netduino code’s startup:

arduino = new OutputPort(SecretLabs.NETMF.Hardware.Netduino.Pins.GPIO_PIN_D12, false);
arduino.Write(true); // turn on Arduino
Thread.Sleep(2000); // give Arduino a chance to do its initialization
lcd = new clsLCD_SFKit(SerialPorts.COM2, 9600, 2, 16);

I added a new method to reset the power to the LCD Kit’s Arduino by temporarily setting D12 low:

static void ToggleArduino()
{
arduino.Write(false);
Thread.Sleep(1000);
arduino.Write(true);
// let Arduino do its initialization
Thread.Sleep(2000);
// restore the brightness setting
lcd.SetBrightness(bytBrightness);

The new method is called when the Netduino hasn’t received a response from the Arduino for over an hour.  It asks for the temperature and humidity every 30 seconds, so an hour is obviously lenient.  If you need the temperature/humidity readings to be more reliable, you should shorten this interval:

// if we haven't received any data from the Arduino for over an hour, reboot it
if (datlastArduinoRead != DateTime.MinValue)
if (DateTime.Now.Subtract(datlastArduinoRead).Hours > 0
datlastArduinoRead = DateTime.MinValue; // prevent another reboot
ToggleArduino();

The voltage out of the Netduino’s digital pins is 5 volts, so why bother with the transistor – why not power the Arduino directly from D12?  The problem is current: the Netduino (and pretty much every microcontroller under the sun) only allows a trickle of current to flow through its pins.  You can power an LED with it, but anything more power hungry needs to get its voltage another way.

Wrapping Up

This installment of the Light Controller project is admittedly off on somewhat of a tangent: connecting a temperature sensor to a Netduino via a Serial LCD interface is not a common configuration.

However, offloading some of the Netduino’s responsibilities onto another processor is actually quite a handy technique.  There are a lot of microcontrollers out there, each with its own libraries of code capable of doing some things that a Netduino can’t (yet), so when looking to add a new feature it’s smart to think “outside the box”.

One other improvement I’ve made to the project is to put the source code into a proper repository, rather than just linking each article to a .zip file.  I’ve created a Google Code project named gigamega-micro.

You can get the code for each of my Netduino articles (starting with Let There Be Light) in 2 ways:

-          If you are familiar with Subversion use SVN to get the latest code.  If you want the older version of the code to match one of the past articles, get the corresponding revision (see the revision list here http://code.google.com/p/gigamega-micro/source/list)

-          Or, download the good old .zip file from the Downloads section of the Google Code project. Here is a direct link to the code for this article.

The modified Arduino code for the Sparkfun LCD Kit can also be found in the Downloads section of the Google Code page (direct link to .zip file).  90% of that code is copied from the original Sparkfun firmware or from Sheepdog Software’s DHT11 page.  I’ve left the original authors’ headers in the code.

Don’t worry, I haven’t forgotten the “road map” of hooking the Netduino up to an XBee.  We’ll get back on track in a future article.

This is the 5th in a series of projects for the Netduino and Seeed Studio’s Grove Starter Bundle.

The first four articles in the series were:

1. Netduino Enters the Grove
2. Netduino: Time and Weather
3. Netduino: Let There Be Light
4. Netduino: Here Comes The Night

Today, my friends, the voice of the people has been heard, and the reign of an oppressive dictator shall finally end.

For too long (about a month-and-a-half, to be specific, since my Netduino: Time and Weather post), we’ve had only one way to enter the date and time and other settings: the user-hostile serial connection. It forced us to drag our notebooks over to the Netduino, open serial terminals, enter obscure commands, and other things too loathsome to mention. Is this any way to live?

The people want freedom. The freedom to just walk up to a Netduino and set the date and time at the click of a button. The freedom to choose Celcius or Fahrenheit, at the click of a button.  (Though only imperialists use Fahrenheit, you know.) The freedom to turn off the LCD backlight – well, you get the idea.

In short, the people want a menu system.

This new menu system will follow the orders of one person only: you the user. Well, technically, also me, the programmer. And if you choose to fix my bugs customize my code, then also you (again), the programmer. Oh, and the reviled serial connection is going to remain in, um, a strictly unofficial capacity to ensure an orderly transition.

Pin Assignments

The pin assignments are unchanged from the previous blog post, Netduino: Here Comes The Night. The changes in this installment of the project are purely software.

User Interface

To invoke the snazzy new menu system, take the Red pill — I mean, press the Red button. (For those who aren’t using the Seeed Grove hardware system, the red button is connected to D7, and the green to D8. In Grove terminology, this is a button “twig” connected to the D7/D8 plug on the Grove stem).

Throughout the menu system, the buttons are used as follows (aaah – a user manual!):

• Red button click – scroll down
• Green button click – scroll up
• Red button double-click – select a menu item
• Green button double-click – exit the current menu

Some of the menus allow you to change a numeric value, like the hour of the day. In these menus:

• Red button click – increase the value by 1
• Green button click- decrease the value by 1
• Red or Green button press and hold – repeatedly increase or decrease the value of the number
• Red button double-click – save the current value of the number and exit the current menu
• Green button double-click – exit the current menu without saving

Programmer Show And Tell

The heart of this update to the project, and the part you are most likely to want to change, is the menu configuration. I didn’t want to reinvent the wheel, so I carefully looked through the work that had already been done on creating a menu system for .Net Micro Framework devices.  When I couldn’t find what I wanted on the first page of the Google results, I got annoyed and reinvented the wheel.

Near the top of Program.cs, you’ll find the following array definition:

static string[] strMenuItems = new string[] {
"1", "Date `yy`-`MM`-`dd`", "1-1",
"1", "Time `HH`:`mm`", "2-1",
"1", "Timers", "3-1",
"1", "Settings", "4-1",
"1-1", "Year `yy`", "_UD-`yy`",
"1-1", "Month `MM`", "_UD-`MM`",
"1-1", "Day `dd`", "_UD-`dd`",
"2-1", "Hour `HH`", "_UD-`HH`",
"2-1", "Min `mm`", "_UD-`mm`",
"3-1", "Light On `HH:mm+`", "3-2",
"3-1", "Light Off `HH:mm-`", "3-3",
"3-2", "Manual `HH:mm+`", "3-2-1",
"3-2", "Sunset `HH:mm_`", "_SUNSET",
"3-3", "Manual `HH:mm-`", "3-3-1",
"3-3", "Sunrise `HH:mm*`", "_SUNRISE",
"3-2-1", "Hour `HH+`", "_UD-`HH+`",
"3-2-1", "Min `mm+`", "_UD-`mm+`",
"3-3-1", "Hour `HH-`", "_UD-`HH-`",
"3-3-1", "Min `mm-`", "_UD-`mm-`",
"4-1", "Temp Fmt `TD`", "4-1-1",
"4-1", "Backlight `LB`", "_BACKLITE",
"4-1", "Brightness `BR`", "_UD-`BR`",
"4-1-1", "Celcius", "_CELCIUS",
"4-1-1", "Fahrenheit", "_FAHR"
};

One thing you’ll notice right away is that this should be a 2 dimensional array (i.e. string[,]), but isn’t. Oddly, there is no such thing as a 2-dimensional array in the .Net Micro Framework. Instead, you can have arrays of arrays (e.g. string[][] strMenuItems = new string[20][], where the 2nd-level array can be of a different size in each element of the main array. This weirded me out, so I went with a 1-dimensional array instead.

Each menu item consists of 3 strings:
- A menu ID – this must be the same for each item in that level of the menu
- A caption, which can contain embedded keywords delimited with the backquote character (`)
- The result of selecting (double-clicking) that menu item, which can be the ID of a submenu to display, or an action (actions are prefixed with an underscore).

So, for example, the first level menu has 4 items that appear on the LCD like this:

Date 11-02-14
Time 18:05
Timers
Tools

The first 2 items contain keywords that are replaced at run-time with the current date and time.
Selecting the first item in this menu displays sub-menu “1-1”, which looks like

Year 11
Month 02
Day 14

Selecting any of these menus selects an action, such as “_UD-`yy`” — this displays an “Up/Down” menu for setting the year. More on that below.

I’ve added a new class to the project, clsLCDMenu, and given it sole responsibility for displaying the menu and handling all button input. This class is intended to be a generalized menu handler: it knows  how to display lines of a menu and allow the user to navigate through the menu using the buttons, but it knows nothing about how to handle the actions selected by the user.

This design results in a fairly extendable and reusable menu. There are no hard-coded limits on the # of elements in a menu of the # of levels of submenus. To add new menu items, or create an entirely different menu system, I won’t have to change any of the code in clsLCDMenu. Instead, I just change the strMenuItems array, above, and add some “action handler” logic to some callback methods in Program.cs, described below.

Since clsLCDMenu “owns” the LCD and buttons when the menu is up, I have to make sure that the existing code never tries to write to the LCD or respond to a button click when the menu is up. I do this by turning off the timers and “unhooking” the button event handlers, as follows:

static void launchMenu()
{
  // turn off the timers that update the display
  timerTemperature.Dispose();
 timerTime.Dispose();

  //unhook the button event handlers
  buttonRed.OnInterrupt -= buttonRed_OnInterrupt;
  buttonGreen.OnInterrupt -= buttonGreen_OnInterrupt;

  // buttonGreen = up, buttonRed = down
  menu = new clsLCDMenu(strMenuItems, lcd, buttonGreen, buttonRed, getStringForMenu, getValuesForMenu,     setValueFromMenu);
}

The “-=” statement that unhooks the event handlers will look freaky to anyone who hasn’t encountered it in .Net before, since neither side of the “-=” is a numeric value. This syntax removes the main class’s button event handlers from a virtual “list” of handlers for the event. It isn’t all that commonly used in .Net, since event handlers are automatically “unhooked” when the class that contains the event handlers is destroyed, such as when a form is closed.

The constructor for the clsLCDMenu class looks like this:

public clsLCDMenu(string[] strItems, ILCD lcd, InterruptPort buttonUp, InterruptPort buttonDown,
MenuCallback getCaption, MenuGetValue getValue, MenuSetValue setValue)

The caller passes a reference to the LCD and “up” (green) and “down” (red) buttons, along with 3 callback methods. The callback methods add the “business logic” to the menu system, if you will: they fill in the keywords in the menu captions, and handle the menu actions. Specifically, there are 3 types of callbacks:

• MenuCallback – gets passed a menu caption containing keywords (e.g. “Light On `HH:mm+`”), and passes back the caption to be displayed to the user (e.g. Light On 20:30”.
• MenuGetValue – gets passed an “up/down” menu definition (e.g. “_UD-`MM`”) and passes back the current value, minimum value and maximum value to be used for the up/down menu.
• MenuSetValue – gets passed an action that needs to be taken: either the changed value from an up/down menu (e.g. the user has changed the hour setting on the clock), or some other action such as “_SUNSET” (the user has set the “Light On” timer to sunset.)

Callback methods in .Net require 2 things:
1) A “delegate” definition. For example, the definitions of the 3 callback methods used by clsLCDMenu are:

public delegate string MenuCallback(string s);
public delegate bool MenuGetValue(string menuType, out Int16 start, out Int16 min, out Int16 max, out byte increment);
public delegate void MenuSetValue(string menuType, Int16 value);

2) The actual method to be executed when the callback is invoked. References to these 3 methods are passed to the clsLCDMenu constructor by the launchMenu() method, shown earlier. The constructor saves these references in variables of the “delegate” type. For example, the MenuCallback is saved by clsLCDMenu as:

private MenuCallback menuGetCaption;

…

public clsLCDMenu(string[] strItems, ILCD lcd, InterruptPort buttonUp, InterruptPort buttonDown,
MenuCallback getCaption, MenuGetValue getValue, MenuSetValue setValue)

…

this.menuGetCaption = getCaption;

When clsLCDMenu needs to call one of the callback methods, it uses its reference variable, calling it as if it was a method. For example:

string strMenuText = menuGetCaption(((menuItem)lstMenu[intMenu]).StrCaption);

I won’t give an explanation of what the callback methods do. They are actually quite straightforward: just a bunch of “if” and “switch” statements that examine the parms to figure out what kind of data they are dealing with, then returning the corresponding settings or taking the corresponding action.

Two other features that are worth explaining, though, are the buttons’ double-click and auto-repeat handlers. These both rely on timers, which are a pleasure to work with in .Net compared to the alternatives that you need to hack together in other microcontroller platforms.

The double-click is a click followed by another click (duh). As every new (or elderly) PC user learns the hard way, the difference between a double-click and 2 single clicks is the amount of time in between.

So, the code which handles the first click sets a timer. If the timer goes off before another click occurs, then that was a single click, and the code handles it accordingly. If a second click occurs before the timer expires, that’s a double click.

The code which sets the double-click timer is:

timerButtonDown = new Timer(new TimerCallback(buttonClick), "Down", DOUBLECLICK_DELAY, -1);

The DOUBLECLICK_DELAY is a constant, in milliseconds, which determines how fast Granny has to move to pull off a double-click. I ended up setting it to 400 ms, which was short enough that I didn’t accidentally double-click when I wanted to make 2 separate clicks.

The “buttonClick” timer event handler now contains the logic that was previously in the button interrupt event: a click isn’t a click until the timer goes off:

private void buttonClick(object data)
{
  if ((string)data == "Down")
  {
    // cancel the button click timer
    if (timerButtonDown == null)
    {
      // oops, someone already cancelled it, so we should ignore it
      return;
    }
    timerButtonDown.Dispose();
    timerButtonDown = null;
    blnButtonDownClicked = false; // no longer waiting for double-click
    goDown();

You’ll notice some seemingly unnecessary null handling.  Here’s the thing…

If the user clicks the button a second time, then we want to cancel this timer event: it’s a double-click action, not a single-click. In theory, disposing a timer should cancel the timer event. However, when testing that code I found that double-clicking would often result in both the double-click and single-click action being performed, since the timer event wasn’t cancelled by disposing the timer object. Setting the timer to null didn’t cancel the event either.

So, I ended up adding code to the timer event to see if the timer had been set to null, and aborting the event if it had. Crude, but effective, and a lot more reliable than polling the button a la Arduino.

To implement button auto-repeat, I used the button “push-and-hold” timer (as described in the Netduino: Let There Be Light article), and had it re-invoke the timer if the button was still being held down:

private void buttonHold(object data)
{
  if ((string)data == "Down")
  {
  …
  if (!buttonDown.Read())
  {
    // not being held down anymore
    return;
  }
  intDownRepeatCount += 1;
  int delay = BUTTONREPEAT_DELAY;
  if (intDownRepeatCount >= 4)
    delay = TURBOREPEAT_DELAY;
    timerButtonDown = new Timer(new TimerCallback(buttonHold), "Down", delay, -1);

As you can see, I implemented auto-repeat the same way as most alarm clocks: the number advances relatively slowly at first (BUTTONREPEAT_DELAY is 500 ms), then more quickly after a couple of seconds (TURBOREPEAT_DELAY) is 200 ms.

Next Steps

At this point in the project, we have a reasonably functional plant light controller (and clock and temperature display).

Although using the new menu to set the date and time is definitely a lot more user friendly than the deposed serial port system (boo, hiss), it’s still a pain to have to re-enter each menu setting after a power outage. So, a battery backup and/or saving the menu settings to flash memory would be a nice feature, and I’ll definitely be adding that at some point.

However, the more exciting enhancement is to give the Netduino something to display on its LCD other than the time and temperature. There is a world of data swirling around the Netduino: twitterers tweeting, bloggers blogging, weather forecasters making stuff up forecasting. Wouldn’t it be cool if our Netduinos could dip into that datastream and display some of that info on its LCD?

There are 2 main options for implementing this: using a Netduino-compatible Ethernet shield to connect directly to the Internet, or using a wireless XBee device to connect to a PC. The first option has the very strong advantage of being a standalone solution, but I’ll be going down the second path – it has the even stronger advantage of me having already written most of the code.

So, if you’re interested in following me there, you’ll want to invest in a couple of XBees, and a couple of hardware interfaces for connecting the XBees to your Netduino and your PC.  More on that in my next article.

The source code for this article can be downloaded here: LightControllerWithMenu.zip. As before, it contains a reference to the Micro Liquid Crystal library, so you should download it as well, and place it in a folder that is side-by-side with my LightControllerWithMenu folder (e.g. c:projectsLightControllerWithMenu and c:projectsMicroLiquidCrystal).

The first three articles in the series were:

1. Netduino Enters the Grove
2. Netduino: Time and Weather
3. Netduino: Let There Be Light

As I hinted at the end of the previous article, there is an easy way to automatically set the plant light to turn on when it starts to get dark. It’s a light-sensing photoresistor (like this), and we’re not going to use it because

1. There isn’t one in the Grove Starter Pack
2. I kinda thought the easiest way would be to calculate the sunset time instead

Using an algorithm to calculate sunset time is actually relatively foolproof, being unaffected by storm clouds, cat attacks, or awestruck bystanders staring at your way-cool plant light controller.

It does however, require 2 additional pieces of information:
- your geographic location
- your timezone, including daylight savings time

The geographic location is, specifically, the longitude and latitude. There are zillions of sources for that on the Internet. One of the handiest is Wolfram Alpha, the Google of calculations. Just type in ” latitude longitude [your city]“, and it will spit out the numbers. Type in “[your city]sunset”, and it will tell you what result the algorithm should be giving you for today.

We all know what timezone we are in, but calculating the start and end date for Daylight Savings Time is too convoluted for most programmers, including me. It becomes pretty easy to determine if your Netduino is Internet connected, but since we aren’t there yet I’ll follow the same approach as the prestigious National Research Council Canada’s Sunrise/Sunset calculator: leave it unimplemented.  (As they put it: “Add one hour to listed times when Daylight Saving Time is in effect.”)

I decided to use the sunset calculation algorithm from this CodeProject article: Solar Calculator.  This API is relatively simple and self-contained. The “LongituteTimeZone” parameter mentioned in the article threw me for a loop – I fruitlessly Googled “Longitute” before realizing that was a typo. This parameter represents your time zone: it is the offset from UTC (aka Greenwich Mean Time) in hours, times 15.    (Turns out each timezone represents 15 degrees of longitude – who knew!)

The algorithm makes extensive use of the trigometry calculations from the .Net Math class, none of which exist in the .Net Micro Framework. Fortunately, all of them do exist, with the exact same parameters, in Elze Kool’s exMath library. This the same library that I used to calculate the temperature in the first article of this series.

So, to change my code to work correctly for your location, you’ll need to change the following 4 values, which are near the beginning of Program.cs in the source code:

// settings for Toronto Canada
const double MY_LONGITUDE = -79.38;
const double MY_LATITUDE = 43.65;
const int UTC_OFFSET = -5;
const bool USE_DAYLIGHT_SAVINGS = false;

Note that the longitude and latitude are in decimal format. If you’ve forgotten your high school geography, negative values are for south of the equator and west of the Prime Meridian, and to convert “minutes” of longitude and latitude to decimals, divide them by 60.

Pin Assignments

If you are using a Parallel LCD, then nothing changes from the list of pin assignments in the Let There Be Light article.

If you are using a Serial LCD, then you probably already changed my pin assignments, since they weren’t at all suitable for a Serial LCD. (As before, you should comment out one of the #define statements at the top of Program.cs to select your LCD type). I changed the code to use:

• UART Serial connection – this changes to COM1 (pins 0 and 1)
• LCD Serial connection – this uses COM2
• Relay twig – this moves from D0 to D13

User Interface

The sunrise calculation is done after the Netduino knows the current date and time. Both of these are still entered using Terminal commands sent over the UART serial connection, as described in the Time and Weather article.

By default, the Light On time is set to 15 minutes before sunset, and the Light Off time is set to 11 pm. You can, of course, override either these using the “+” and “-” Terminal commands described in the Let There Be Light article.

If you have an 16×2 LCD (or larger), it will display the Sunset time on the 2nd row, next to the temperature. This has little practical value other than to confirm that the sunset times are being calculated correctly (and impress friends who are easily impressed).  You can comment it out if you like in the displayTemperature() method.

Speaking of the accuracy of the sunset calculation: it isn’t all that accurate for me (in Toronto Canada). Depending on the day of the year, it is 5-10 minutes earlier than what Wolfram Alpha and other web sites calculate. I get the same result when I run the CodeProject code on a Windows PC, so whatever is responsible isn’t MathEx or the .Net Micro Framework. For the purposes of a plant light, 5-10 minutes is close enough.

Programmer Show and Tell

The most interesting code change this time is something that didn’t work as expected. As described in the Let There Be Light article, I’m using the exotic and mysterious ExtendedTimer class to raise events for turning the light on and off. This class has a Period parm, which is how often you want the timer event to repeat. Since we are now recalculating the “light on” time on a daily basis, I wanted to turn off the period. The MSDN docs for the ExtendedTimer constructor say you do this with Timeout.Infinite

tmrLightOn = new ExtendedTimer(new TimerCallback(SetLightState),
  true, datAlarm,
  new TimeSpan(Timeout.Infinite));

Unfortunately, this doesn’t work, not on a Netduino anyway. It throws an “Argument out of range” exception. The best workaround I could find was to set it to the maximum TimeSpan value.

TimeSpan tsRepeat = TimeSpan.MaxValue;

if (!blnLightOnAtSunset)
{
   // repeat timer at same time every day
   tsRepeat = new TimeSpan(1, 0, 0, 0);
}

tmrLightOn = new ExtendedTimer(
  new TimerCallback(SetLightState),
  true, datAlarm, tsRepeat);

The other piece of code that I’ll point out is the use of a custom event to notify the main class that the user has entered a date and time. The clsUART class has a UART_DataReceived event that fires every time something is entered by the user in a serial terminal. It handles things that it knows how to do (like set the system date and time), then fires off an event to notify the rest of the application that the command was received. This allows you to cleanly separate the serial port logic in clsUART from the “plant light” logic in the main application class.

For example, the code in clsUART that handles the Date command includes the following:

DateTime currentDayTime = new DateTime(intYear,
  Int16.Parse(strDateParts[1]),
  Int16.Parse(strDateParts[2]),
  DateTime.Now.Hour,
  DateTime.Now.Minute, DateTime.Now.Second);

Utility.SetLocalTime(currentDayTime);

// tell rest of application that the date has been set
raiseCommand(strCommand);

if (blnSendResponse)
{
  WriteToUART("OK");
  return true;
}

The raiseCommand method looks like this:

public event CommandEventHandler Command;

private bool raiseCommand(string strCommand)
{
   CommandArgs args = new CommandArgs(strCommand);
   // raise event using Command delegate
   Command(this, args);
   return args.blnHandled;
}

It uses a parm passed to the CommandEventHandlers to determine if some other part of the program recognized the command and handled it. The return code is ignored in the above “date command” logic (since clsUART already handled it), but it is important for commands that clsUART doesn’t know how to handle, like setting turning the plant light on or off. If it gets a false parm back, it displays an error message to the user. (Well, it actually displays a “?” and buzzes a little, but you get the idea.)

Currently, the only CommandEventHandler is in Program.cs. It is created during startup by the following:

uart = new clsUART(strUARTPort, 9600, 50, true);
uart.Command += new CommandEventHandler(uart_Command);

The event handler includes this:

static void uart_Command(object sender, CommandArgs e)
{
   if (command == '-')
   {
      e.blnHandled = setLightTime(e.StrCommand.Substring(2), false);
   }
   else if (command == 'D')
   {
      blnDateSet = true;
       // set default light timer if date and time have been set for the first time
      setDefaultTimers();
  }

So, the code uses the e parm to return a confirmation that it took care of the command (if it did).

That’s it for this installment – a simple change that could have been simpler.  (Clearly George Vernon Hudson wasn’t a programmer.)

Next up, I’ll be adding a menu system for things like setting the date and time.  I notice that the current version (1.0b) of the Grove Starter Kit now includes a 16×2 LCD, rather than the tiny 8×2 model that the beta Starter Kit shipped with, so I’ll use that as the minimum screen size for the menu.

The source code for this article can be downloaded here: LightControllerV2.zip. As before, it contains a reference to the Micro Liquid Crystal library, so you should download it as well, and place it in a folder that is side-by-side with my LightController folder (e.g. c:projectsLightControllerV2 and c:projectsMicroLiquidCrystal).

This installment is intended to create a plant light that automatically switches on and off at a pre-set time of the day (well, more usefully, the night).  It is inspired by the “Garduino” project, which was published in Make Magazine and can also be found on Instructables.

This project builds on the foundation set by the earlier two articles. If you want to actually get the project working yourself, you’ll probably need to browse the earlier articles, especially the part about the serial connection to the PC.

The first two articles  in the series were:

Netduino Enters the Grove

and

Netduino: Time and Weather

As the project develops it will soon be necessary to move beyond the Grove’s components (that 8×2 display, in particular, is cramping my style).  First, though, we’re going to bring another Grove component into the act: the Relay twig.

The Relay twig is used to switch the plant light off and on.   To connect the relay to the plant light, we first need to splice open an AC extension cord.

Now, I know that Edison fellow has been spreading the word about AC power being dangerous and what-not.  Sounds scary, don’t it?  Well, it’s true!  Ask Topsy the Elephant.

Seriously, though, various unpleasant things can happen if you hook the relay up incorrectly, but fortunately the risk is mainly to the relay, and your self-esteem.  However, since you don’t want your relay Twig to end up like poor Topsy,  I’ll spend much of this article covering the process of  making that connection.

You actually have a couple of options: build or buy.

Option 1 – Modify an Extension Cord

Here’s the plan: The Relay twig acts as a on/off switch for the extension cord.  The twig has two little green screw connectors.  The “live” wire of the extension cord needs to be cut open, and the 2 exposed ends need to be inserted into those 2 green connectors.  Sounds simple, and it is.

The following photo shows a modified 2-prong extension.  It also shows the connection to the Relay twig, but don’t worry about that for now – it is explained in the “Connecting the Relay Twig” section, below.

Two-pronged extension cord connected to Grove Relay

The process of modifying the extension cord isn’t complicated or dangerous. Anything you do wrong will be evident before you get to the stage where you’ve got the extension cord plugged into the wall. However, it does requires some soldering and some common sense.  If you’re not confident about your abilities at either of these, consider Option 2, below.

The extension cord you use doesn’t need to be anything special – the cheapest one at Wal-Mart is good enough.  If your plant light has a three prong plug then, of course, you need to buy a three prong extension cord.

The best guide to what’s required (and the one I originally followed) is the one in the Make magazine Garduino article. The Instructables version of Garduino refers you to 2 other sites.  Personally, I found the Hobby Robotics article to be confusing (so many wires!) and the Sparkfun article to be downright intimidating (you don’t have to pull a power receptacle out of the wall for this project).  As far as I know the Make Magazine article isn’t available to non-subscribers, but it just so happens that someone (not me) has posted a PDF of this article here.  To modify the extension cord for use with Relay twig, follows steps 7a-7c.

The Make magazine article shows how to modify a two-prong extension cord.  If your plant light requires a 3-prong cord, then the only difference is the process of selecting the right wire to cut and splice.  

It must be the “live” one, which for both 2- and 3-prong cords is the one connected to the narrower blade of the plug.  Generally, the corresponding wire in the cord is aligned with the blade of the plug (i.e. if the blade is on the left, you need to cut the cord on the left).   However, to make sure that you’ve selected the right one before cutting it, nick the cord to expose the copper underneath, then use a multimeter to check connectivity with the narrower blade of the plug.  (If you picked the wrong cord, it’s safe to cover the nick with electrical tape, as I did with the 3-prong extension cord in the photo below.)

Three-pronged extension cord connected to Seeed Relay Brick

Option 2 – Buy a Netduino-Friendly Extension Cord

A product called the “PowerSwitch Tail” recently became available.  It is specifically intended to be hooked up to microcontroller circuits, such as the Arduino and Netduino.  It contains a 5V relay similar to the one in the Grove starter kit – if you go this route, you can ignore the Grove relay.  You’ll have to connect a wire from the Powerswitch to the D0 pin of the Netduino (or modify my code to use whichever pin you’d like).  Then, just skip ahead to the “First Test” section below.  You can read more about the PowerSwitch on the Adafruit product page and in Adafruit’s forums.

I haven’t tried a PowerSwitch, but I’m 99.9% sure it will work fine with the Netduino and this project.

Connecting the Relay Twig

You should have two wires with exposed tips coming from your extension cord.  As you probably figured out, you need to connect each wire into one of the screw connectors on the Relay twig.  Ah, but which goes into which?

Unfortunately, Seeed didn’t put any markings on the v0.9 Relay twig to help you out.  The Datasheet and tutorial on Seeed’s web site don’t offer any guidance on this either.  (“If in doubt contact a professional such as a licensed electrician for help“.  Uh, yeah, good luck with that.)

However, the HLS8L-DC5V relay happens to be the exact same model as used in Seeed’s Electronic Brick relay, and the Brick relay is well documented in this Instructables article and in this Seeed Forum post.

The Grove relay has removed one of the Brick’s 3 screw connectors, meaning that the only way you can hook it up is “normally open”.  This means that the extension cord won’t (yeah, “open” means “off” – go figure) conduct electricity when your Netduino project is powered off.

The 2 screw connectors are, then, are the “Common” and “NO” connectors shown in the Instructables article.  As with its big brother, the Seeed Relay Brick, the twig’s Common connector is on the left (when the screw connectors are facing you) and Normally Open is on the right.  See the photos in this post.

Important Note: this is true for the “0.9″ version of the twig, which is the first version that was sold.  If your twig doesn’t say 0.9 on it, then I’d strongly suggest you double-check this information, either by using a multimeter or by checking the Seeed product page or forum.  Seeed recently posted an article about version 1.0 of the Grove Starter Bundle.  The Relay twig photo on that page looks more like a Relay forest, so if your twig is bristling with relays then all bets are off!

To check continuity with a multimeter, you want to confirm that the “Common” left-hand screw connector is connected to the middle pin at one end of the black relay box, and the other screw connector is connected to one of the 2 pins at the other end of the black relay box. I think the best illustration of the orientation of the pins for this relay is the one in the Seeed forum thread.

Grove Relay Brick - hooked up and ready to rock

OK, so at this point you should have an UNPLUGGED extension cord that is connected to an unplugged relay twig.   This is the time to ensure that you’ve firmly and securely connected the extension cord to the relay.  Tug  hard on the relay twig to make sure that it doesn’t come loose from the extension cord.  

Carefully inspect the points at which the wires from the extension cord are plugged into the screw connectors of the Grove twig.  There must not be any exposed metal from the wire.  If there is, insert the wire further into the screw connector or, if the exposed metal is simply too long, snip it shorter.

That cord-to-relay connection is the only dangerous (to you) part of the setup, and you definitely don’t want to have a wire come loose after you plug it in!

Incidentally, if you Googled for information about the HLS8L-DC5V relay, you may have been unsettled to find that there isn’t much out there, aside from a bunch of pretend-datasheet-sites gaming Googling search engine.  However, I’ve had 2 of the Seeed bricks with this relay in daily service for about 6 months now, and never had a problem with either of them.  So, for what its worth, I’m pretty comfortable with this relay, safety-wise.

Initial Test

I’ve written a small test project, RelayTester, that you can use to test turning the relay off and on.  Pressing the green button (connected to D8) toggles the relay.

Start by unplugging everything from the Grove shield.  Reconnect to the Grove shield just 2 twigs: the one with the red and green buttons (connected to plug D7/D8) and the Relay twig (connected to D0, and to an UNPLUGGED extension cord).  Yes, there, is such a thing as D0 on the Grove shield, off to one end, as shown in the photo in the “Final Configuration” section, below.

Deploy the test project to the Netduino.  For this part of the test, you can leave the Netduino plugged into the USB port of the PC.

The red light on the relay may briefly go on and then off when the Netduino boots up.  Press the green button on the button twig, and the red light should come on and stay on.  Press the green button again to turn it off.

Do you hear a fairly loud clicking noise from the black relay box each time the red light goes on or off?  If not, something is wrong.

If the red light on the relay works, but there is no click, try using a different cable between the Relay twig and the Netduino.  If that doesn’t help, try a different connector than D0 (you’ll have to change the test program code accordingly, of course).

If the red light doesn’t come on at all, check that the connectors are plugged into the Grove shield correctly (buttons in D7/D8, relay in D0, and nothing else connected), and that the project was deployed to the Netduino correctly.  (It will display messages to the Visual Studio Debug window when turning the relay on or off).

If that’s not the problem, then you might have a bad relay twig and should check the Seeed forums or e-mail them.

Live Test

I don’t think there is much risk to the Netduino if things aren’t hooked up correctly.  The Netduino isn’t exposed to the AC current – that’s the whole idea of the relay.  The biggest risk is to the relay itself, and possibly to whatever you have plugged into your extension cord.  However, as an extra precaution, I’d suggest you have as little as possible connected to the Netduino: the Grove shield, the button twig and the relay twig.

Also, I’d suggest you power the Netduino from a DC adapter rather than the PC’s USB port.  The concern isn’t that the relay is power-hungry, but that you want to protect your PC’s USB port if things go wrong.    (If you haven’t run the Netduino with that DC adapter before, rerun the above “Initial Test” with the extension cord still unplugged from the wall.)

OK, so it’s all been fun and games so far, but no fooling around for this test. Remember Topsy!

1. Plug the plant light (or a cheap test light) into the extension cord.
2. Plug the extension cord into the wall.
3. Plug the DC adapter into the Netduino.
4. Press the green button.  Let there be light!
5. Leave the light turned on for awhile, periodically touching the extension cord, the wires leading from the extension cord to the relay, and black relay box to make sure it isn’t getting hot.  The cord and wires shouldn’t get warm at all; the relay box will be very slightly warm.

One last (I promise!) comment about safety: ideally you should never make any adjustment to the relay/extension cord/light setup with the extension cord plugged in.  When hooking things up, and when adjusting the setup, unplug the extension cord first.  Keep an eye on those 2 screw terminals on the Relay twig and the wires inserted into them — that’s the danger zone.  Don’t pile anything on top of them, don’t let those wires get snagged on something.

Final Configuration

OK, let’s bring the rest of the Grove twigs back on stage.  (Not you, Prototype Twig, we aren’t ready for you yet.  Oh, and Tilt Switch twig, um, you can run along home.  We’ll keep you in our files, and we’ll call if we need to do any tilting).

The configuration is the same as in the previous project, Time and Weather, with the addition of the Relay twig:

• D0/D1 – Relay
• D2 – jumper to TX pin of serial header on breadboard
• D3 – jumper to RX pin of serial header on breadboard
• D4/D5 – right side of LCD stem, lower connector
• D6/D7 – piezo buffer twig (only D6 is used)
• D7/D8 – button twig
• D9/D10 – bottom of LCD stem, right connector
• D11/D12 – bottom of LCD stem, left connector
• D13 – right side of LCD stem, upper connector
• A0 – modified potentiometer (unused for Grove LCD, or any other LCD without a software backlight control)
• A2 – temperature twig

Final Configuration of the Netduino and Grove components. Can't see the forest for the trees!

By now, you’ve probably noticed that I have a strange aversion to pin D1.  What’s up with that?

Well, I have 2 Netduinos, one for development and one for testing.  My test Netduino suffered an unfortunate accident, resulting in it being, um, “differently abled” on the D1 pin.

Wait, what?   The guy who’s  giving you safety tips electrocuted his Netduino?

Well, not on this project – honest!  I’m actually not sure at what point it stopped working, but I suspect it occurred while experimenting with the not-particularly-dangerous-but-not-Netduino-friendly Danger Shield.  (See my “Spiderman: The Musical” project for details).

The source code for the LightController project can be downloaded here.

As with the test project, press (and, this time, hold) the green button to manually turn the relay (and light) on and off.  You can also program it to turn off and on at a certain time, using the handy serial port connection from the previous project.  (Stop groaning, we’ll get rid of the serial port in a later project, I promise.)

The 2 new commands are:

+:hh:mm

Sets the time at which the light will come on

-:hh:mm

Sets the time at which the light will go out.

There is no default on and off time – you have to set them manually for now.  (Since you have to set the Netduino’s clock manually, there wouldn’t be much point to having default timer settings).

I’ve also added some new button features, pretty much exhausting the possibilities for the 2-button twig:

• Press the red button: Toggles LCD between the regular time/temperature display, and a display of the  Light On and Light Off times.   If all you see is “+” and “-”, with no times, then you need to set the times using the serial terminal “+” and “-” commands, as described above.
• Press and hold red button: Toggles the serial port off and on, as described in the “Time and Weather” article.
• Press the green button: toggles the first row of the LCD between the current time and a countdown to the next light “event”.  That is, if the light is currently on, it shows a countdown to when the light will go off.  And vice versa.
• Press and hold green button: toggles the light off and on.
• Press and hold red and green button: clears the light on and light off timer.  Also makes your fingers hurt.

Programmer Show And Tell

The new code has a few features worth mentioning.

The light on/off timers are implemented using the ExtendedTimer class.  This is the lesser known of the 2 .Net Framework timers.  It is better suited than the Timer class for time events that occur at specific times of day, rather than at intervals.

For example, the code to set the “light on” timer is:

// set the timer to go off at this date, and every 24 hours after that
tmrLightOn = new ExtendedTimer(new TimerCallback(SetLightState), true, datAlarm, new TimeSpan(1, 0, 0, 0));

Since we want the light to come on at the same time each day, the ExtendedTimer constructor does all the work. There is no need to reset the timer for the next day when the timer event fires.

The countdown timer takes advantage of the fact that, in .Net, subtracting one date from another returns a TimeSpan that gives the difference between them:

// relay is off, display time to next light-off
string strCountdown;
if (datNextOn == DateTime.MinValue)
{
    strCountdown = "Not set";
} else
{
   TimeSpan timeTo = datNextOn.Subtract(DateTime.Now);
   strCountdown = timeTo.ToString();
}
lcd.SelectLine(1, true);
lcd.WriteStringToLCD(strCountdown);

Note that DateTime (and TimeSpan) objects can’t be null – an unset DateTime has a value of DateTime.MinValue.

And lastly, this projects makes extensive use of the 2 pushbuttons. I really like the fact that all the button features can be implemented in the .Net MF without polling.  

Buttons can be configured as InterruptPorts.  The InterruptPort constructor has a parm that lets you specify when the event should be triggered — when you press the button, when you release the button, or both. The following code specifies both:

buttonRed = new InterruptPort(Pins.GPIO_PIN_D7, true,
   SecretLabs.NETMF.Hardware.Netduino.ResistorModes.Disabled,
   SecretLabs.NETMF.Hardware.Netduino.InterruptModes.InterruptEdgeBoth);

The event handler needs to handle 2 cases: a short push and a push-and-hold.  The handler can’t know which it is until the button is released.  On the other hand, the user would like to have some confirmation of the push-and-hold action before letting go.  The answer is to set a timer (the regular kind) on the button press.  If the button is released before the timer goes off, that’s a short push.  If the timer expires first, then that’s a push-and-hold.  I use a 2-second timer.

Here’s the button’s event handler. The same event handler is fired when the button is pressed and when it is released. The state parm tells you which event it is.

static void buttonRed_OnInterrupt(uint port, uint state, DateTime time)
{

  if (state == 1)
  {
     // start the button hold timer
    timerButtonRed = new Timer(new TimerCallback(buttonHold),
       buttonRed, BUTTON_DELAY, BUTTON_DELAY);
  }
  else
  {
     // cancel the button hold timer
     if (timerButtonRed != null)
     {
        timerButtonRed.Dispose();
      }
      if (blnButtonHeld)
      {
         // timer went off, so ignore the release
         blnButtonHeld = false;
         return;
      }

      // normal button press - handle it

      . . .

Note that .Net MF timers are turned off using the .Dispose method – there is no property for setting a timer’s active state.

Last, here’s the timer’s event handler.  I decided to have the red and green button share the same button timer, so a parm is passed to indicate which button it is.  

A boolean variable is used to tell the button’s event handler to ignore the button’s release event when the user eventually lets go.  

Note that, in order to implement the double-button-hold feature for clearing the timers, the code checks the state of the other button using the .Read method, same as you would if you used polling to check the buttons.

private static void buttonHold(object data)
{

  // tell the button release event to ignore it - we're handling it
  blnButtonHeld = true;

  if ((InterruptPort)data == buttonRed)
  {
     // cancel the button hold timer - otherwise, this event will go off again if user keeps button pressed
     timerButtonRed.Dispose();

     // if both buttons are held down, clear the light timers
     if (buttonGreen.Read())
     {
        // cancel the green button's timer
        timerButtonGreen.Dispose();

        clearTimers();
     }
     . . .

So what’s next for this project?  Needless to say, this project is badly in need of an improved user interface, so a menu system can be used to replace (or supplement) the serial port commands.  This will require that we say bye-bye to the tiny 8×2 Grove LCD.

This post is a continuation of my “Netduino Enters the Grove” article.   Building on the project in that post, I’m going to make the Netduino a more productive member of society by having it display the time, in addition to the temperature.

I’m also going to add to the mix a couple more “twigs” from the Seeed Grove Starter Kit: the 8 x 2 LCD, and the piezo buzzer.

Lastly, I’m going to make use of the Netduino’s serial port to show how to make it communicate with a PC.

Adding the Grove Parallel LCD

The Seeed Grove LCD - all the news that 8 x 2 can fit. Click to enlarge.

The Grove Starter Kit comes with a rather odd LCD: a cramped 8 x 2 board bristling with 24 pins, 6 of them for voltage and 6 for ground.

Since documentation isn’t Seeed’s strong suit, this has led to some head-scratching about the best way to connect the LCD to an Arduino. I wasn’t too optimistic about getting it to work with a Netduino, which is one of the reasons I went with a serial LCD in my earlier post.

However, it turned out to be relatively straightforward to connect, thanks to Szymon Kobalczyk’s excellent MicroLiquidCrystal library.

The LCD connectors that you need to use are the 2 on the right and the 2 on the bottom. The pins are labelled on the back of the LCD’s  ”stem” board – clockwise from the upper right  connector (and ignoring the voltage and ground pins) they are RW, NC (unused), RS, EN, D4, D5, D6 and D7. These are the pins used in almost any LCD library based on the HD44780 chipset, including one of the constructors of the MicroLiquidCrystal library. (MicroLiquidCrystal supports other types of connections that use fewer digital ports, but for the purpose of testing the Grove LCD’s default configuration I’ll stick to the more traditional GPIO connection for this project).

The 2 key lines of code are:

GpioLcdTransferProvider lcdProvider =
     new GpioLcdTransferProvider(rs, rw, enable, d4, d5, d6, d7);
Lcd lcd = new Lcd(lcdProvider);

In my project, I’ve added a wrapper class to MicroLiquidCrystal in order to make to compatible with the 2 other devices I use when testing: a Matrix Orbital serial LCD and a Sparkfun Serial LCD Backpack (as described in my earlier article). So, the code which calls the above methods is in the clsLCD_MLC constructor in the attached source code:

public clsLCD_MLC(Cpu.Pin rs, Cpu.Pin rw, Cpu.Pin enable, Cpu.Pin d4,
    Cpu.Pin d5, Cpu.Pin d6, Cpu.Pin d7, byte rows, byte cols)
{
// NOTE - RW pin is needed for Seeed's Grove LCD
lcdProvider = new GpioLcdTransferProvider(rs, rw, enable, d4, d5, d6, d7);
//lcdProvider = new GpioLcdTransferProvider(rs, enable, d4, d5, d6, d7);
lcd = new Lcd(lcdProvider);
SetScreenSize(rows, cols);
lcd.Write("hello, world!");
Thread.Sleep(500); // greet the world and give the LCD time to get its act in order

The call to this code specifies what pins are being used. The configuration shown in the photos uses the following:

lcd = new clsLCD_MLC(Pins.GPIO_PIN_D4, Pins.GPIO_PIN_D13, Pins.GPIO_PIN_D5,
Pins.GPIO_PIN_D9, Pins.GPIO_PIN_D10, Pins.GPIO_PIN_D11, Pins.GPIO_PIN_D12, 2, 8);

So, the 4 Grove cables are connected to the Grove shield using (clockwise from the upper right): D13/NC, D4/D5, D9/D10, DD11/D12. Actually, I’m pretty sure that any 4 connectors (or 7 pins) would work just as well. I went with these in order to save the serial port pins and one of the PWM pins  for other uses.

The LCD tutorial in the Grove documentation suggests that a 6 pin connection is also possible (minus the RW pin), but I couldn’t get that to work with either the Arduino or Netduino.

By the way, if you are trying your Grove LCD for the first time and nothing appears on the screen, the first thing to check is the contrast control. This is a little metallic potentiometer on the LCD “stem” board – it looks like a brass screw-head. If you don’t see a line of block characters when you first power-up the LCD, then turn the potentiometer counter-clockwise, then try again.

There are a few drawbacks to the Grove LCD compared to other parallel LCDs. The first and most obvious is the size – 8 x 2 characters is OK for the time and temperature, but won’t be enough for future projects. The backlight is “always on”, with no easy way to control that. Presumably, it can be controlled by connecting one (hopefully not all 4!) of the connectors’ voltage pins to a digital PWM pin. However, I haven’t tried this myself yet). The 2 connectors on the bottom, combined with the stiff connector cables, makes mounting the LCD somewhat of a mechanical challenge, as you can see in the photo.

And yet it works. I tested the Netduino Time/Temperature gadget for a couple of days, and the LCD didn’t display any garbled characters or have any other problems.

Adding the Grove Piezo Buzzer

The buzzer connection is quite straightforward. You can connect it to any digital pin if you just want it to buzz, or to a PWM pin if you want to give it a greater musical range. The Netduino has just four PWM pins, 5, 6, 9 and 10. For the purpose of this project, I’m using pin 6.

Since PWM is not supported by the underlying Micro Net Framework, its implementation is left up to the hardware maker. As with Seeed Studios, documentation doesn’t seem to be Secret Labs’ strong suit – they definitely know how to keep a secret. This makes the process of controlling the buzzer a little tricky to figure out. I found the best source to be the full-featured and well-documented code in this post by Ray Mckaig on the Netduino forums.

This is a low-end buzzer, so its musical range runs the gamut from annoying to tortuous. The following code makes 2 types of sounds: an annoying ding-a-ling somewhat like a cordless phone (when the parm is true), or a tortuous beeeeeep that my cat really, really dislikes.

public static void Beep(bool blnUp)
{

blnBeeping = true;
float fltFreq = 10;
int intDuration = 1000;
if (!blnUp)
{
fltFreq = 30;
intDuration = 1000;
}

uint period = (uint)(1000000 / fltFreq);
buzzer.SetPulse(period, period / 2);
Thread.Sleep(intDuration);
buzzer.SetDutyCycle(0);

}

Setting the time through a serial port

Netduino's serial connection - click to enlarge

(Secret Labs has recently added a firmware feature that allows your program to use the USB port as a serial device, and use one of the Netduino’s serial ports for deploying code and debugging, but I haven’t tried that out yet.)

When using a Netduino serial port for communication with a PC, you’ve got 2 problems: the voltage level sent and received on the Netduino’s pins (3.3V) is much lower than what the PC sends and receives, and the communication protocol used by the Netduino (TTL) is not the same as what the PC uses (RS-232).

Fortunately, there is a relatively inexpensive device that solves both problems: a 3.3V FTDI cable. This is widely available at hobby electronics retailers such as Adafruit and Sparkfun. If you use an Adafruit Boarduino, Solarbotics Ardweeny, Secret Labs’ own Netduino Mini, or some other microcontroller-based device that doesn’t include a USB port, then you probably already have this cable.

With the cable, connection of the Netduino to a PC pretty simple. Only 3 of the cable’s coloured connectors are used: the black cable (ground) should be connected to ground, the orange cable (TX) should be connected to the RX pin of one of the Netduino’s 2 COM RX pins (pin 0 or 2) and the yellow cable (RX) to one of the Netduino’s TX pins (1 or 3).

In the photo of my setup, I’ve inserted a 5 pin male header like this into the breadboard.   You’ll need to adjust the pins in the header slightly so that they stick out about the same amount on both sides of the header.  Since I’m using COM2 on the Netduino,  the white jumper cable goes from the breadboard to pin 2 and the yellow jumper to pin 3.

The code to open the COM port is in the constructor of my “clsUART” class:

public clsUART(string strPort, Int16 intBaud, int intReadBufferLen, bool blnSendResponse)
{

SerialPort UART = new SerialPort(strPort, intBaud, Parity.None, 8, StopBits.One);
UART.Open();
UART.DataReceived += new SerialDataReceivedEventHandler(UART_DataReceived);
Debug.Print(strPort + " Opened at baud " + intBaud);
WriteToUART("Hello World");

And the call to this constructor is:

uart = new clsUART(SerialPorts.COM2, 9600, 50, true);
uart.Command += new CommandEventHandler(uart_Command);

A couple of things to note about using the MNF’s SerialPort:
- In order to use the Net MF’s SerialPort class, the Project References must include a reference to Microsoft.SPOT.Hardware.Serial. This isn’t included by Visual Studio in a new Netduino project by default – it has to be added manually

PuTTY settings, with some (partially overwritten) terminal commands in the background. Click to enlarge

One of the nice things about the FTDI cable is that the chip which handles the RS-232 communications with the PC is embedded in the cable, and therefore it is ready to go as soon as you plug the cable into the PC. You can then use PuTTY (or your serial terminal of choice) to connect to whatever COM port the PC assigns to the cable. If there is nothing at the other end of the cable, other terminal screen will remain empty, but you won’t get any errors either.

More PuTTY settings - note the Local Echo option. Click to enlarge

However, if you “hot plug” the FTDI cable into your Netduino when it is already up and running, you’ll likely find that the connection doesn’t automagically start working – you have to reset the Netduino’s COM port. I added some code to handle this by pressing and holding the red button. This toggles the COM state on or off, sends a message  to the LCD, Visual Studio’s Debug window, and the PC serial’s terminal, and makes a buzzer noise (the annoying one when the port goes down, the tortuous one when the port comes back up).

If your PC’s serial terminal displays “Hello world” when the Netduino boots up, or “Hello again world” when you toggle the port open with the red button, then the Netduino is yours to command. It knows the following commands:

Set time:
T:hh:mm[:ss]
e.g. T:14:35

Set date:
D:yyyy-mm-dd
e.g. D:2010-12-29

Set temperature format (Celcius or Fahrenheit):
F:F|C
e.g. F:C

Set LCD backlight:
L:ON|OFF
e.g. L:OFF

Set LCD brightness:
B:nnn where nnn is 0-255
e.g. B:128

The Netduino will respond to a valid command by sending “OK” to the terminal.  Generally the LCD will immediately be updated with whatever setting you changed. However, in the case of the 8 x 2 Grove LCD setting the date and changing the backlight or brightness has no effect.

Should you enter a command that the Netduino doesn’t recognize, it will send a “?” to the terminal and making the annoying sound with the buzzer, so type carefully!

All things considered, this is probably the simplest way to set the time on the Netduino, but also the least convenient.  (A clock that has to be set using a serial port – Grandma’s worst nightmare!).

In future posts, I plan to demonstrate a few other methods: an on-screen menu (more convenient, but  lots of coding), an Ethernet shield (very convenient for the user – it sets itself – but not so convenient if you don’t happen to have an Ethernet port nearby) and a wireless XBee connection (very very convenient, très cool, and my platform of choice for a lot of projects).

Note: The source code for the project described in this post can be downloaded here.  The .zip file contains 2 folders: one (ClockAndTemperature) with my source and one (MicroLiquidCrystal) with the MicroLiquidCrystal library.  The latter is a separate project that is loaded by the ClockAndTemperature solution file.  The 2 folders should therefore be stored in the same parent folder.

I recently received one of Seeed Studio’s new Grove Starter Bundles. Since many others will put GROVE through its paces using an Arduino — and Seeed recently posted a series of projects that do just that — I thought it would be interesting to try it out with a Netduino instead.

For those unfamiliar with these two products, Grove is a set of plug-and-use electronics components, like sensors and controls, intended to be used with an Arduino-compatible shield. The Netduino is a .Net Micro Framework-based system that uses the same form factor and pinout as the Arduino.

Why Grove?

Netduino meets Seeed Grove

The closest competitor to Grove that I know of is the Phidgets systems. Seeed’s product is considerably less expensive and, in my experience, the quality is just as good. The Phidgets system, on the other hand, has top quality documentation, and can be directly interfaced with PCs without using an *duino go-between.

The advantages of GROVE over Seeed’s Electronic Bricks are, frankly, yet to be revealed. The GROVE components can use 2 pins, not just 1. In some cases this allows one component (they’re called twigs, actually) to include 2 separate items, such as 2 pushbuttons or 2 LEDs.

However, I think the real reason for the double-pin support is that the “twigs” contain edge connectors which would allow them to be directly connected to one another. You can see what I mean by looking at the photos of the various components on this page. Those markings on the edges of each twig’s circuit board (VCC, GND, D1, D2 etc.) are pads that align with those on other twig’s boards. I’m honestly not sure where that is leading, since the Grove was just released and the documentation is a work in progress, but I assume that the goal isn’t just to reduce cable usage. Stay tuned.

Why Netduino?

If you are a programmer, or learning to become one, then the advantages of Secret Lab’s Netduino over the Arduino are clear.

The Netduino’s IDE is Microsoft’s venerable Visual Studio 2010, which absolutely bristles with features when compared to the Arduino’s IDE. The free Visual Studio C# 2010 Express is well suited to Netduino development, since the extra features found in the other Visual Studio versions generally don’t apply to microcontroller programming.

And, even more importantly, the Netduino supports In Circuit Debugging, using nothing more than a USB cable. No more trial-and-error debugging and testing! As Joe Biden would say, that is a Big F’ing Deal!

If you aren’t a Windows user,the the disadvantages of the Netduino over the Arduino are also clear. ‘Nuff said. The Arduino also has a larger and more established hobbyist community, and is probably a better choice for somebody new to coding.

The Netduino has a close competitor, the FEZ Panda from GHI. GHI has actually been in the .Net Micro Framework game a lot longer than Secret Labs, and their firmware and documentation are therefore much, much better. When Netduino first came along this summer, it had a clear price advantage over GHI’s first Arduino-compatible board, the Domino. GHI quickly responded with a budget board called the Panda, Secret Labs responded with a feature-rich board, the Netduino Plus, and the fight is on!

But, back to the point of this article: Netduino’s adventures in the Grove.

Digital Components

The first things I tried were some basic digital components, and they worked pretty much seamlessly.

Grove shield and twigs

I tried connecting a button twig and LED twig (2 per twig in each case), and programmed them so that the buttons triggered the lights to glow and dim, using PWM. Initially, the button event (yes, the .Net Micro Framework fully supports raised events, just like Bill Gates invented ) didn’t fire. A bit of trial and error revealed that the pulldown resistor had to be disabled, which is easily done in the source code.

The Netduino has relatively limited PWM support when compared to the Arduino (you can set the period, but frequency is fixed at 10Khz), but it worked fine with the LEDs. GHI’s firmware allows the frequency to be set, which might come in handy with the Grove’s piezo buzzer.

I’m using a serial LCD connected to digital pin 3 and the 5V and Ground pins. That setup works as expected. The Grove Starter Bundle includes a parallel LCD,  However, since the Netduino has 2 serial ports, neither of which are used to program or debug the board, and its support for parallel LCDs is less well established than the Arduino’s a Serial LCD might be the best way to go with the Netduino any way.

I’m using an elderly Matrix Orbital serial LCD, but the Sparkfun Serial LCD Backpack is a relatively inexpensive way to convert a parallel LCD to serial, including 4×20 LCDs. I’ve included support for it in the attached source code — just comment out the corresponding #define at the top of Program.cs. I took advantage of the .Net Compact Framework’s support for Interfaces to create compatible classes for the 2 serial LCD APIs.

Incidentally, both the analog and digital pins of the Netduino supply 5V, even though the processor uses 3.3V, which improves compatibility with Arduino shields. However, while the digital pins can accept 5V input, the analog pins (or, more accurately, the analog-to-digital converter) cannot go beyond 3.3V. That presents a problem when using 5V sensors and controls like the Grove’s.

Analog Components

For example, the potentiometer twig would, when turned all the way up, flood the ADC and cause all of the analog pins to read weird values. The proper solution for this is to connect the pot (and any other analog twig you use) through a circuit that converts the 5V signal to 3.3V or lower.

A voltage divider works well for something like a pot, since accuracy isn’t all that important. However, I tried a more accurate (though more cumbersome) approach using Sparkfun’s Logic Level Converter.

Sparkfun Logic Level Converter - Simplicity is for wimps!

Lastly, to make things interesting, Sparkfun decided to step the signal down to 2.5V, not 3.3V as the product description suggests. The step up, on the other hand, always goes to 5V. Presumably, this decision was made to allow compatibility with microprocessors that use other voltage levels, but it means an extra step (pun intended) when what you want is a 3.3V signal.

Generally, you would correct the reading in code (by multiplying it by 3.3/2.5). Another option is to use the Netduino’s AREF connector to feed in the actual analog voltage you want to use. So, I connected it to AREF to a 2.5V signal from the Sparkfun converter, requiring yet another pair of wires – a connection to the 5V bus on the input side, and a connection from the output side to AREF.

Messy, but effective. The pot twig’s signal now moves smoothly from 0 to 1023 while staying well within the Netduino’s tolerance.

Next up, the temperature sensor twig. I tried the same connection approach as with the pot. Actually, since the Sparkfun Logic Level Converter only supports 2 input signals, I setup a second converter on the breadboard for this. While the converter correctly stepped the analog voltage down, the resulting temperature calculation was 34C (93F). This overshot the correct reading by about 12C.

I’m not 100% sure what the cause is, but I think the problem is that the temperature twig’s sensor uses a logarithmic scale, and simple fractional conversions don’t work in that world. (If anyone knows differently, please post a comment with an explanation).

A good solution, which has been described in the Netduino forums, is to use a temperature sensor that connects via I2C rather than an analog pin. However, I went with a hack. The analog signal returned by the Grove system’s temperature sensor (assuming you are using it for room temperature, and aren’t in Hell) is safely below the 3.3V threshold supported by the Netduino’s ADC. So, you can get away with connecting it directly to the shield, and the same temperature calculation formula used with the Arduino then works correctly with the Netduino.

Well, it almost works. The formula in the Grove system’s tutorial makes use of the Arduino’s (technically, AVR Libc‘s) log() function, which calculates a natural logarithm. The .Net Micro Framework doesn’t have a log() function. .Net’s Math function was pared down for size, and log() didn’t make the cut.

I first tried an alternative formula, taken from a forum posting for the older Electronic Brick temperature sensor. This came close, but was about 0.5C too high.

So, I next tried incorporating Elze Kool’s exMath library, which includes a log() function. After waiting, and waiting, for the logarithm calculation to complete, I broke into the debugger (again, in-circuit debugging is a Big Freaking Deal!!) and found it caught in an infinite loop.

while (partial >= double.Epsilon)
{
   if (x >= newBase)
   {
      fractional += partial;
      x = x / newBase;
   }
   partial *= 0.5F;
   x *= x;
}

The comparison of partial to epsilon kept returning true, even though the debugger showed the value of partial to be 0. In fact, entering partial > epsilon in Visual Studio’s Immediate window correctly returned false - only the compiled code was getting it wrong.

I can only assume that this is a bug in the compiler — epsilon is, after all, the mother of all edge cases. Adding (partial == 0) to the while loop’s condition fixed the problem. The temperature calculated by this formula is almost dead-on.

This leaves us with one last problem: the hack of using the “raw” signal from the 5V temperature sensor isn’t compatible with the earlier hack of feeding a 2.5 voltage into the AREF pin. Since the AREF problem is easily fixed in software, I changed the AREF signal to 5V, and doubled the reading from the potentiometer twig.

Watch it Spidey, it's Dr Octopus!

Source Code Notes

A few notes on the hardware setup used by my code:

1. The button twig is connected to D7/D8, and the LED twig to D9/D10.
2. The temperature sensor twig is connected to A2/A3,
3. The potentiometer twig is connected to A0. As explained this connection is via the Sparkfun Logic Level Converter. The “D1″ (why D?) pin of the pot is actually connected by a jumper cable to the RI pin of the Converter, and the corresponding RO pin of the Converter to the A0 pin of the shield. If you want to skip the hassle of the analog voltage conversion, you can omit the potentiometer. It is used only to set the backlight level of the LCD. Just comment out the call to setLCDBrightness in Program.cs.
4. The Serial LCD is connected to D3. You can run the code without a serial LCD by commenting out both #define statements at the top of Program.cs. You can see the temperature value in the Visual Studio Debug output window, and the buttons and LEDs will still work as normal.

The MathEx library is included in its entire, original form, except for the one change I made as explained above.  The change is commented with date 12/12/10.

And one final note: if you are thinking that a temperature display is a horrible waste of the Netduino’s capabilities, I agree entirely. This is just a starting point for a series of refinements that I’ll blog about in the future. I currently have various Arduinos scattered about my house, controlling plant lights, displaying Twitter feeds and weather forecasts, and logging temperature data. The code required a lot of trial-and-error debugging, and relies on the use of a Beagleboard as a go-between to the Internet. I’m looking forward to seeing how much more (or less?) the Netduino can achieve.

The source code for the temperature LCD program described in this article can be downloaded here.

However, I was a little surprised that they didn’t include the source code for the Windows program that communicates with the board. Sending a “hello world” message to the LCD is fine for verifying that the kit works, but an LCD connecting to a PC could be used for so much more.

When Googling for some .Net code that I could use as a starting point for writing my own interface, I was delighted to find that somebody had already done most of the work for me. An article on The Code Project site describes the construction of a homebrew parallel port LCD connection, and includes the C# .Net code that the creator used to send data to the LCD. Out of curiosity I downloaded the code and ran the .exe to see what happened, and I was astounded to see it successfully writing The Code Project’s RSS feed to the kitsrus LCD, under Vista no less. “Hello World”, indeed.

The Code Project article’s creator wasn’t using the kitrsrus kit, but because his LCD is based on a similar controller chip, and by a lucky coincidence in the selection of parallel port pins, the code mostly worked. The only problem was that the data wasn’t scrolling across the LCD as intended, but was stuck in the last column of the display, writing only to that one position. The data was getting across, it just wasn’t being positioned correctly. This is a pretty common and easily solved problem when writing data to an LCD, as I’ll explain below.

(In order to preserve your sanity and mine, I’ll refrain some referring to “the Code Project project” and the “kitsrus kit”, and call them the “CP project” and “the kit”. Apologies to their respective trademark owners.)

Although there is no “standard interface” for connecting an LCD to a parallel port, there is a fairly close correspondence between the parallel port’s pins and the pins used by all LCDs that use an HD44780-compatible controller chip. (Most LCDs intended for use by hobbyists are compatible with this standard, dating back to the late 90s. The Wikipedia entry for HD44780 links to an Everyday Practical Electronics article from 1997.)

The CP project used an LCD based on an old Samsung KS0066 chip, and the kit contains an LCD based on the KS0070 and manufactured in 1999, and both of those are HD44780-compatible.

The Code Project author wrote 2 articles that contain all the technical information you need to know in order to understand his .Net source code: this article covers the parallel port’s pins, and this one covers the LCD’s. The illustration below is linked to his second article.

Both the parallel port and the LCD use 8 data pins, D0 through D7. Not surprisingly, both the CP project and the kit wire the 2 sets of pins in a one-to-one correspondence, D0 to D0, D1 to D1, etc. The data sent by the .Net code arrives just fine at the LCD, then.

LCDs based on the HD44780 interface also have 3 control pins: RS (register select), R/W (read/write) and E (enable). Since LCDs don’t have much to say, both the CP project and the kit do the same thing with the R/W pin – wire it to ground, putting it in a permanent write state.

By a happy coincidence, both the CP project and the kit happened to wire parallel port pin C0 to the E pin of the LCD – without pin C0 turning things off and on, nothing would have made it to the LCD. There is a non-intuitive pattern of setting the enable pin low then high then low again that is necessary to write data to the LCDs — this seems to be the thing that trips up most novice LCD programmers, but the CP project’s source code does a nice job of commenting this code so that you can understand what’s going on.

The only area where the 2 approaches differ is in the selection of the RS pin: the CodeProject board uses pin C2 while the kitsrus board uses C1. (See the CP project’s pinout diagram below). Since this pin is used to tell the LCD whether it is receiving data or instructions, and the pin needs to be high for data, this difference should have caused everything being sent to the LCD to the treated as instructions, resulting in a jumpy cursor but no characters on the screen. However, by another lucky coincidence, the parallel port pin used by the kit, C1, is reversed – it is normally high and is set to low by sending it a “1″. This results in everything sent to the LCD being treated as data — characters with no cursor control, exactly what we got.

Parallel port connections to the LCD, by Levent Saltuklaroglu, courtesy of The Code Project

To adapt the CP project’s code to the kit, the only change required is to redirect all signals intended for C2 to C1, and flip the bit from allow for the fact that kit’s pin is reversed.

I decided to implement this change by adding a go-between method that would convert the instructions sent by the CodeProject code to the ones required by the kitsrus board:

        private void writeToControl(int intValue)
        {
            int intModifiedValue = intValue;
            if ((intValue & 4) > 0)
				// if C2 is being set  high, set C1 high by sending it a 0
                intModifiedValue = intModifiedValue & 253;
            else
				// else, if C2 is being set low, set C1 low by sending it a 1
                intModifiedValue = intModifiedValue | 2;

            PortAccess.Output(intControl, intModifiedValue);
        }

And that’s it — the kit can now be fully controlled by the CP project’s code.

This is quite cool, since it breathes new life into a 10-year old kit. When originally introduced the kit had only a command line interface that would only run in DOS – real DOS, not the command line in Windows XP. However, the .Net code works just fine under Vista and Windows 7. By tinkering with the code you can now use the LCD as a remote display for whatever you like: RSS feeds, e-mail, twitter. A poor geek’s Chumby!