Platform Creation and Testing

Lesson 10a: Platform Creation and Testing

Last updated 15 August 2007 A new platform wiring debug tool with only three code files.

We have a fairly simple goal -- to harness GPIOs so we can control them and see what they are inputting on a MSP430 based platform. Seeing means displaying, so we will use the three LEDs found on many MSP430 platforms to display a 3 bit binary number corresponding to pin0 through Pin7 that we wish to test. This module is for MSP430 testing purposes so will never need Hardware Independent HIL modules -- we will come to that in 10b. The tests this code helps with are whether a new printed circuit board has traces going to the right MSP430 IO ports.

With a HAL, (hardware adaptation layer), configuration and code file plus a HPL, (hardware presentation layer), configuration and code file we would have 4 files. Since we reuse the GeneralIO interface with new names and add no new functions, we can do without a code file. So we have just three files, (beyond all the core tinyOS modules), for this exercise. The HPL configuration file maps connections from any port names predefined in the MSP430 chip directory to our desired group of eight ports named Pin0 - Pin7. The HPL file is part of a new platform, defined by a new directory added to the tinyos source code tree: /opt/tinyos-2.x/tos/platforms/ecosens1p. Some necessary parts for a new platform variant were copied from telosb: PlatformC.nc MoteClockC.nc MoteClockP.nc PlatformP.nc. They set up the clocks and initialize the MSP430. Also needed in this new platform is hardware.h, which was copied from telosb and modified to change names to leave off the humidity sensor, and rename some GeneralIO signal names.

Creating a new platform

There is plenty of ground work done for us, so the first steps of this process are copying -- This example code can run on an unmodified telosb hardware. Some details you will see are specific to an Ecosensory platform, but they don't stop you from learning by making the IO tester program below on any telosb derived platform. So copy from telosa and telosb and update .platform file and remember support/make/*.target -- see lesson 10. To use the tutorial as is, the name of the platform can be ecosens1p, p for prototype, but it will be better to use your own name and get the hang of it more. When you are done copying your new dir should look like this:

  john@ecolab:/opt/tinyos-2.x/tos/platforms/ecosens1p$ ls
  ActiveMessageC.nc     MoteClockP.nc                 SwitchToggleC.nc
  chips                 MotePlatformC.nc              TelosSerialP.nc
  DemoSensorC.nc        MSP430ADC12ChannelConfigM.nc  UserButtonC.nc
  DemoSensorNowC.nc     Msp430Timer32khzMapC.nc       UserButton.h
  DemoSensorStreamC.nc  PlatformC.nc                  UserButtonP.nc
  hardware.h            platform.h                    VoltageC.nc
  HplNew8IOsC.nc        PlatformLedsC.nc              VoltageStreamC.nc
  HplUserButtonC.nc     platform_message.h
  MoteClockC.nc         PlatformP.nc

To simplify we will learn about the bottom, close to the hardware, HPL layer of tinyOS modules first, then add HAL and HIL top level and generic modules in lesson 10b.

GPIO Tester program

The configuration file called TestNewPlatformIOC.nc, declares standard telosb tinyos parts MainC, userButtonC, LedsC, TimerMilliC() and then the program module TestNewPlatformIOP.nc, and a new component:

components  HplNew8IOsC;
 TestNewPlatformIOP.Pin0 ->  HplNew8IOsC.Pin0;
 TestNewPlatformIOP.Pin1 ->  HplNew8IOsC.Pin1;

The arrows in a configuration file point in the direction of more specific hardware, or the root of a definition, whether pointing left or right. The above arrows connect references in the program sequence file to the hardware presentation layer file specific definition, so this file can have different versions depending on platform. If two versions are made, they will be in different platform or sensorboard dirs, and have the same name, HplNew8IOsC.nc. This snippet from HplNew8IOsC.nc shows reusing interface GeneralIO with new names.

configuration HplNew8IOsC {

 provides interface GeneralIO as Pin0;
 provides interface GeneralIO as Pin1;
            etc....

Next, declaring the HPL for the MSP430.

implementation {

 components HplMsp430GeneralIOC;

Then a generic MSP430 component is instantiated with 8 names -- we will get into details of this in lesson 10b.

components new Msp430GpioC() as myPin0;
 components new Msp430GpioC() as myPin1;

Then connections are made from the names to specific MSP430 port pins, that number many more than 8. We are just declaring a way to use 8 because we have a goal of displaying with three bits! We have a widespread beginner display in the three LEDs, able to generate some excitement in a newbie, so we use them. A future tutorial that repeats this program for another platform would be a nice learning tool.

 myPin0 -> HplMsp430GeneralIOC.ADC0;  // = Port60
 myPin1 -> HplMsp430GeneralIOC.ADC1;  // = Port61
 Pin2G  -> HplMsp430GeneralIOC.ADC2;  // = Port62

Notice the names for our 8 IOs can be anything in this file, they are local, and can't be used anywhere else. To use this program as a hardware testing tool, you can redefine the right sides of the above list to suit, using names from HplMsp430GeneralIOC.nc , and put them on a piece of paper with room to the side to write notes, then load the program on the new platform hardware and apply current limited 2.8 or 2.9volts if your batteries are at 3.0 Volts, and see changes in LED output as you select Pin0 or Pin5 or Pin7 by pressing the user button to count through the LED displayed numbers. Telosb hardware has some pull down resistance on the inputs of GPIOs -- I didn't need to pull inputs down to get a LO, and the input voltages measured between .001 and .05 Volts. The sequences and flashing times used can be changed in TestNewPlatformIOP.nc if you want a different "user interface"...

Here is the core of the TestNewPlatformIOP.nc program, showing use of the new names for MSP430 port pins:

 event void Timer.fired() {    
   periodhalf = !periodhalf; //every other time period get a pin value.
   if (counter == 0x0)  { pinHi = call Pin0.get();

You could get fancier displaying the pin number or the pin value read. What is more important for understanding tinyOS is that Pin0.get() is a renaming of GeneralIO.get, one of the built in interfaces, and that it has been mapped to a specific port using names from HplMsp430GeneralIOC.nc. In HplMsp430GeneralIOC.nc we see lines like:

 ADC0 = P60;

1. ifdef __msp430_have_port6

 Port60 = P60;

Port60 has two names. Both work fine -- Port60 or ADC0. P60 is a local name not usable anywhere else.

By John Griessen www.ecosensory.com copyright 2007

Related Documentation

   * TEP 2: Hardware Abstraction Architecture
   * TEP 107: TinyOS 2.x Boot Sequence
   * TEP 109: Sensors and Sensor Boards
   * TEP 114: SIDs: Source and Sink Independent Drivers
   * TEP 117: Low-level I/O
   * nesC reference manual
   * TinyOS Programming Guide