Embedded Developer

In the previous post a prototype for the multiple digital outputs was developed and implemented on breadboard. The STM8S code was independent and demonstrated that two chained 74HC595 shift registers could be controlled by bit-banging data through GPIO pins on the STM8S.

In this post we will continue the development of the module by merging the code from the previous post with the STM8S module code from the post STM8S SPI Slave (Part 3) – Making a Go Module. We will develop both the STM8S code and the NETMF driver to implement the following functionality:

• Clear the shift registers
• Set the outputs of the two shift registers

These two functions are already in the standalone version of the STM8S code and it should be a relatively simple exercise to merge this functionality with the Netduino Go Bus communication protocol.

STM8S Application

The first task to be completed for the STM8S code is to create a new project and add the code from the post STM8S SPI Slave (Part 3) – Making a Go Module. The two functions should then be removed and the two new ones we are implementing should be added.

Start a New Project

Start a new STM8S project and save the project into a new directory. Now take the source code in main.c from the project STM8S SPI Slave (Part 3) – Making a Go Module and paste over the code in you new project. Ensure that the project is targeting the correct microcontroller and save the project.

Alternatively, copy the project code from STM8S SPI Slave (Part 3) – Making a Go Module into a new directory.

Remove Dummy Functionality

The project code in the STM8S module post contained a couple of dummy functions illustrating the concept of module functionality and communications. This code should be removed and the application stripped down to the basics required for SPI communication with the Netduino Go!.

Add New Functionality

The final task is to add the code which implements the new functionality as defined for the basic module (i.e. clear the shift registers and set the outputs of the shift registers).

The first thing which is required is to add the #define statements to support the bit-banging:

//--------------------------------------------------------------------------------
//
//  Pins which we will be using for output the data to the shift registers.
//
#define SR_CLOCK            PD_ODR_ODR3
#define SR_DATA             PD_ODR_ODR2
#define SR_CLEAR            PC_ODR_ODR3
#define SR_OUTPUT_ENABLE    PC_ODR_ODR4
#define SR_LATCH            PD_ODR_ODR4

The InitialisePorts method will also need to be modified in order to ensure that the ports above are all setup correctly. We need these to be output ports capable of running at up to 10MHz. The code becomes:

//--------------------------------------------------------------------------------
//
//  Initialise the ports.
//
void InitialisePorts()
{
    //
    //  Initialise Port D.
    //
    PD_ODR = 0;             //  All pins are turned off.
    PD_DDR = 0xff;          //  All pins are outputs.
    PD_CR1 = 0xff;          //  Push-Pull outputs.
    PD_CR2 = 0xff;          //  Output speeds up to 10 MHz.
    //
    //  Initialise Port C.
    //
    PC_ODR = 0;             //  Turn port C outputs off.
    PC_DDR = 0x18;          //  PC3 & PC4 initialised for output.
    PC_CR1 = 0x18;          //  PC3 & PC4 Push-Pull outputs
    PC_CR2 = 0x18;          //  PC3 & PC4 can run up to 10MHz.
    //
    //  Initialise the CS port for input and set up the interrupt behaviour.
    //
#if defined(DISCOVERY)
    PB_ODR = 0;             //  Turn the outputs off.
    PB_DDR = 0;             //  All pins are inputs.
    PB_CR1 = 0xff;          //  All inputs have pull-ups enabled.
    PB_CR2 = 0xff;          //  Interrupts enabled on all pins.
    EXTI_CR1_PBIS = 2;      //  Port B interrupt on falling edge (initially).
#else
    PA_ODR = 0;             //  Turn the outputs off.
    PA_DDR = 0;             //  All pins are inputs.
    PA_CR1 = 0xff;          //  All inputs have pull-ups enabled.
    PA_CR2 = 0xff;          //  Interrupts enabled on all pins.
    EXTI_CR1_PAIS = 2;      //  Port A interrupt on falling edge (initially).
#endif
}

The application will also need some storage space for the data in the shift registers:

//--------------------------------------------------------------------------------
//
//  Number of registers in the chain.
//
#define NUMBER_OF_REGISTERS     2
//
//  Data area holding the values in the register.
//
U8 _registers[NUMBER_OF_REGISTERS];             //  Data in the shift registers.

Note that the variable used to store the data in the registers has been converted into a static array instead of a variable sized array using malloc.

The function table needs to be modified to hold the references to the methods which will implement the module functionality:

//
//  Forward function declarations for the function table.
//
void SetShiftRegisters();
void ClearShiftRegisters();
//
//  Table of pointers to functions which implement the specified commands.
//
FunctionTableEntry _functionTable[] = { { 0x01, ClearShiftRegisters }, { 0x02, SetShiftRegisters } };

The next step is to add the methods which will implement the functionality:

//--------------------------------------------------------------------------------
//
//  Clear the shift registers.
//
void ClearRegisters()
{
    for (U8 index = 0; index < NUMBER_OF_REGISTERS; index++)
    {
        _registers[index] = 0;
    }
}

//--------------------------------------------------------------------------------
//
//  GO! Function 1 - Clear the shift registers.
//
void ClearShiftRegisters()
{
    ClearRegisters();
    OutputData();
    NotifyGOBoard();
}

Note that the functionality has been implemented using two methods, the first ClearRegisters is the internal implementation. This is independent of the Netduino Go! communications and allows the functionality to be called in say the initialisation code of the module. The second method, ClearShiftRegisters is the method which is called by the code as determined by the Netduino Go! driver code. This has the additional output and notification methods which actually sets the data in the shift registers and sends a signal back to the Netduino Go! to let the board know that the request has been received and processed. Note that this split is not necessary but is a design decision taken for this particular module.

The code should be ready to compile and deploy to the STM8S.

Netduino Go! Driver

At this point we should have one half of the communications channel ready to test. The second stage is to implement the driver on the Netduino Go!. As our starting point, we will copy the code from the BasicGoModule class in the post STM8S SPI Slave (Part 3) – Making a Go Module into a new class OutputExpander. We will modify this to add create new functionality to clear and set the shift registers.

Command Constants

The first this we need to do is to remove the old command constants and add two new ones:

/// <summary>
/// Command number for the ClearShiftRegister command.
/// </summary>
private const byte CMD_CLEAR_REGISTERS = 1;

/// <summary
/// Command number for the SetRegister command.
/// </summary>
private const byte CMD_SET_REGISTERS = 2;

Modify the Supporting Methods

The existing code in the module can be optimised for this module. To do this rename the WriteDataToModule method to WriteDataToSPIBus. Now add the following code:

/// <summary>
/// Write the data in the _writeFrameBuffer to the module.  Make several
/// attempts to write the data before throwing an exception.
/// </summary>
/// <param name="exceptionMessage">Exception message to the used in the constructor if the write attempt fails.</param>
private void WriteDataToModule(string exceptionMessage)
{
    int retriesLeft = 10;
    bool responseReceived = false;

    WriteDataToSPIBus();
    while (!responseReceived && (retriesLeft > 0))
    {
        //
        //  We have written the data to the module so wait for a maximum 
        //  of 5 milliseconds to see if the module responds with some 
        //  data for us.
        //
        responseReceived = _irqPortInterruptEvent.WaitOne(5, false);
        if ((responseReceived) && (_readFrameBuffer[1] == GO_BUS10_COMMAND_RESPONSE))
        {
            //
            //  Assume good result, it is up to the calling method to determine if
            //  the command has been executed correctly.
            //
            return;
        }
        else
        {
            //
            //  No response within the 5ms so lets make another attempt.
            //
            retriesLeft--;
            if (retriesLeft > 0)
            {
                WriteDataToSPIBus();
            }
        }
    }
    throw new Exception(exceptionMessage);
}

By making this change we are also making the assumption that the signal back from the module (via the interrupt) is always indicating success. This is a decision which is appropriate for this module but may not be appropriate for other applications/modules.

Add New Functionality

Before adding new functionality it is necessary to remove the existing AddFive functionality from the BasicGoModule.

Out OutputExpander module will provide the application with two basic functions:

• Clear – clear the shift registers setting the output to 0
• Set – Set the values in the shift registers to those specified by the parameters

This functionality is provided by the following code:

/// <summary>
/// This method calls the ClearRegister method on the GO! module and then waits for the
/// module to indicate that it has received and executed the command.
/// </summary>
public void Clear()
{
    _writeFrameBuffer[0] = GO_BUS10_COMMAND_RESPONSE;
    _writeFrameBuffer[1] = CMD_CLEAR_REGISTERS;
    WriteDataToModule("Clear cannot communicate with the Output Expander module");
}

/// <summary>
/// Set the shift registers using the values in the byte array.
/// </summary>
/// <param name="registers">Bytes containing the shift register values.</param>
public void Set(byte[] registers)
{
    if (registers.Length != 2)
    {
        throw new ArgumentException("registers: length should be 2 bytes");
    }
    _writeFrameBuffer[0] = GO_BUS10_COMMAND_RESPONSE;
    _writeFrameBuffer[1] = CMD_SET_REGISTERS;
    for (int index = 0; index < registers.Length; index++)
    {
        _writeFrameBuffer[2 + index] = registers[index];
    }
    WriteDataToModule("Clear cannot communicate with the Output Expander module");
}

Testing

At this point we should be able to add some code the Main method of the application to test the module. We will perform something similar to the code in the previous post, we will move a single LED but this time we will illuminate the LED starting a position 15 and working down to 0. This should ensure that we have deployed new code to both the module and the Netduino Go! board.

public static void Main()
{
    OutputExpander output = new OutputExpander();
    int cycleCount = 0;
    byte[] registers = new byte[2];
    while (true)
    {
        Debug.Print("Cycle: " + ++cycleCount);
        for (int index = 15; index >= 0; index--)
        {
            output.Clear();
            if (index < 8)
            {
                registers[0] = (byte) (1 << index);
                registers[1] = 0;
            }
            else
            {
                registers[0] = 0;
                registers[1] = (byte) (1 << (index - 8));
            }
            output.Set(registers);
            Thread.Sleep(200);
        }
    }
}

The test breadboard and Netduino Go! were connected through the Komodex GoBus Breakout Module. This allows the Netduino Go! and the ST-Link/2 programmer to be connected to the breadboard:

Output Expander Connected to Netdunio GO!

And here is a video of this working:

You can just see the Netduino Go! in the bottom left corner of the video.

Conclusion

At this point the basic concept has be proven and the application can perform the following:

1. STM8S code can control one or more LEDs
2. STM8S can be controlled using SPI
3. Netduino Go! can pass instructions to the STM8S

One thing that did become apparent during this part of the process was that both the STM8S code and the Netduino code can be improved by improved grouping the functionality. For instance, in order to add the methods to the function table in the STM8S code I had to jump around the source code a little.

The next step in the process is to look at the hardware and start to prepare for prototype PCB manufacture.

So the first stage in the development process (now we have the concept) is to develop a working prototype on breadboard. This will show if we can make the hardware and software work as we want to achieve the desired goals.

Connecting up a Single 74595

For the first stage we will connect up a single 74HC595 shift register to a STM8S chip and write some software for the chip. We are not going to consider connecting the STM8S to other chips/controllers at the moment, we are simply going to output some known data to the shift register and see how it responds.

As this is a simple digital output board we can show the output from the system by using some LEDs. This will also allow us to test one of the secondary objectives, namely the ability to control a reasonable amount of current. The standard 74HC595’s will supply/sink up to 25mA per pin. However, the chip is only rated at 150mW. Turning on all of the pins will over drive the chip. So to get around this we will drive the LEDs through a transistor/MOSFET.

Breadboard Prototype

Looking at the data sheet for the 74HC595 we have 5 control signals to connect to the STM8S:

The serial input lines of the 74HC595 lend themselves to the using the SPI bus in order to send data to the shift registers. We will not be able to use SPI in this case as we will need to reserve this for communication with the Netduino Go!.

Connecting the 74HC595

The second shift register should be connected to the same signals as the first except the serial data in line. This should be connected to the serial data output line of the first shift register. In this way the data is cascaded from the first register to the second and so on. The resultant schematic looks this this:

Shift Register Schematic

The next task is to connect the shift registers to the STM8S. As SPI is already reserved for communicating with the Netduino Go! the data will have to be transferred by bit-banging the data. The following connections should be made between the STM8S and the first 74HC595:

The above schematic becomes:

STM8S and Shift Registers Schematic

Connecting the LEDs

Visual output from the shift registers will be provided by a number of LEDs. In order to reduce the current drawn from the shift registers the LEDs will be driven by a transistor/MOSFET.

Full Circuit

When assembled, the full circuit looks something like this:

Prototype On Breadboard

Software

A small application is required to test the circuit. The first stage is to verify that the STM8S can communicate with the shift registers. The application will simply turn on the various LEDs connected to the shift registers in turn.

Firstly, we need some #define statements to make the code more readable.

#define SR_CLOCK            PD_ODR_ODR3
#define SR_DATA             PD_ODR_ODR2
#define SR_CLEAR            PC_ODR_ODR3
#define SR_OUTPUT_ENABLE    PC_ODR_ODR4
#define SR_LATCH            PD_ODR_ODR4

The application will use a small array of bytes to indicate the status of each pin on the shift register. A small helper function will allow the previous contents of the register to be cleared:

//
//  Clear all of the bytes in the registers to 0.
//
void ClearRegisters(U8 *registers, U8 numberOfBytes)
{
    for (U8 index = 0; index < numberOfBytes; index++)
    {
        registers[index] = 0;
    }
}

The final helper function will output the data to the shift registers:

//
//  BitBang the data through the GPIO ports.
//
void OutputData(U8 *data, int numberOfBytes)
{
    //
    //  Initialise the shift register by turning off the outputs, clearing
    //  the registers and setting the clock and data lines into known states.
    //
    SR_OUTPUT_ENABLE = 1;               //  Turn off the outputs.
    SR_LATCH = 0;                       //  Ready for latching the shift register into the storage register.
    SR_DATA = 0;                        //  Set the data line low.
    SR_CLOCK = 0;                       //  Set the clock low.
    SR_CLEAR = 0;                       //  Clear the shift registers.
    __no_operation();
    SR_CLEAR = 1;
    //
    //  Output the data.
    //
    for (int currentByte = 0; currentByte < numberOfBytes; currentByte++)
    {
        U8 b = data[currentByte];
        for (int index = 7; index >= 0 ; index--)
        {
            SR_DATA = ((b >> index) &amp; 0x01);
            SR_CLOCK = 1;               //  Send a clock pulse.
            __no_operation();
            SR_CLOCK = 0;
        }
    }
    //
    //  Set the clock line into a known state and enable the outputs.
    //
    SR_CLOCK = 0;                       //  Set the clock low.
    SR_LATCH = 1;                       //  Transfer the data from the shift register into the storage register.
    SR_OUTPUT_ENABLE = 0;               //  Turn on the outputs.
}

The final code required is the main program loop which will drive the shift registers:

//
//  Main program loop.
//
void main()
{
    //
    //  Initialise the system.
    //
    __disable_interrupt();
    InitialiseSystemClock();
    //
    //  PD3 and PD2 are used for the serial data going to the registers.
    //  Configure Port D for output.
    //
    PD_ODR = 0;             //  All pins are turned off.
    PD_DDR = 0xff;          //  All pins are outputs.
    PD_CR1 = 0xff;          //  Push-Pull outputs.
    PD_CR2 = 0xff;          //  Output speeds up to 10 MHz.
    //
    //  PB4 and PB5 are used for control of the output and clearing the
    //  registers.  Configure Port B for output.
    //
    PC_ODR = 0;             //  All pins are turned off.
    PC_DDR = 0xff;          //  All pins are outputs.
    PC_CR1 = 0xff;          //  Push-Pull outputs.
    PC_CR2 = 0xff;          //  Output speeds up to 10 MHz.
    __enable_interrupt();
    //
    //  Main loop really starts here.
    //
    numberOfRegisters = 2;
    registers = (U8 *) malloc(numberOfRegisters);
    ClearRegisters(registers, numberOfRegisters);
    OutputData(registers, numberOfRegisters);
    while (1)
    {
        int counter = 0;
        while (counter < 16)
        {
            ClearRegisters(registers, numberOfRegisters);
            if (counter < 8)
            {
                registers[0] = (1 << counter);
            }
            else
            {
                registers[1] = (1 << (counter - 8));
            }
            counter++;
            OutputData(registers, numberOfRegisters);
            for (long index = 0; index < 100000; index++);
        }
    }
}

The code above turns on an LED, pauses and then moves on to the next LED. This is repeated until all of the LEDs have been illuminated. The cycle then repeats from the start. The following video shows this working:

Conclusion

At this point we have proven that the STM8S can be connected to the shift registers and we can turn on one of more LEDs connected to the output of the shift registers.

The next post in this series will connect the STM8S to the Netduino Go! and present a basic driver for the Netduino Go!, enough to illustrate that the Netduino Go! can control the shift registers.

This series of posts will examine the activities required to take the concept of a module for the Netduino GO! through to production.

Project Definition

A simple project will allow the series of posts to concentrate on the principles required for the production of a Netduino GO! module without being too distracted by the functional aspects of the module. The following project definition should meet this brief:

• Provide 16 or more digital outputs
• Work with the Netduino GO!
• Low cost manufacture
• Use simple tried and tested components/techniques

Meeting the Objectives

As you can no doubt see, this is a reasonably simple project and with the exception of cost, we should have no major problems reaching the objectives. The most obvious solution to this problem is to look at using 74HC595 serial to parallel chips. These are cheap components and the techniques needed to solve this type of problem are tried and tested. The project definition looks like the counting example which is discussed in the Counting Using 74HC595 Shift Registers post with the addition of the Netduino Go! functionality.

Project Plan

Initial assessment of the project indicates that the following steps are required in order to take the project from concept to manufacture:

1. Build a hardware prototype using the STM8S103F3 to control two shift registers. This will have some form of visual output to prove that we can control the digital lines (probably some LEDs)
2. Write the software for the STM8S which will control the output of the 74HC595 chips
3. Generate the schematic for the board
4. Layout a prototype board and send to manufacture
5. Write the software for the Netduino GO! while waiting for the manufactured boards to turn up
6. Assemble a prototype on one of the prototype boards
7. Conclusion

The first post in the series will build the breadboard prototype and start to control the LEDs using the STM8S.

The STM32 contains several clocks each of which can be turned on or off when not used. In this post we will examine the clocks available and how they can be configured. To do this we will modify the simple GPIO example to change the clock parameters. Any changes to the system clock speed will increase or decrease the period of the delay. The results can be seen using an oscilloscope. We will look at the following topics:

• Clock Sources
• System and Peripheral Clocks
• Microcontroller Clock Output
• Configuring the Clock

At the end of this post you should be able to configure the system clock and introduce a known delay subject to the tolerances of the system clocks.

Clock Sources

The STM32 Reference Manual (RM0090) states that there are five clocks available:

• High Speed Internal (HSI) oscillator
• High Speed External (HSE) oscillator
• Phase Locked Loop (PLL)
• Low Speed Internal (LSI) clock
• Low Speed External (LSE) clock

As already noted, each clock can be turned on/off as required. Turning an unused clock off reduces the power consumption of the microcontroller.

The first three clocks are used to drive the system clock for the microcontroller. The final two are low speed clocks and are primarily used to drive the watchdogs.

HSI

After reset, the STM32 enables the HSI oscillator. This has a relatively low accuracy, only 1%, but is suitable for most applications. Using the HSI oscillator eliminates the need for an external clock in the final circuit design. On the STM32F4, the HSI oscillator has a clock speed of 16 MHz.

HSE

The STM32 can operate using an external clock circuit. It is possible to design an external clock to run with a greater accuracy than the internal HSI clock enabling finer control of the operating parameters of the final circuit. The exact specification of the external clock frequency varies but is typically 4-16 MHz.

The STM32F4 Discovery Board has a built in external oscillator circuit fitted with a 8 MHz crystal.

PLL

The PLL is used to multiply it’s input clock source by a factor varying between 2 to 16. The input of the PLL is one of HSI, HSE or HSE/2.

It is important to note that the configuration of the PLL cannot be changed once it has been enabled.

LSI

The LSI is a low power clock used for the watchdog timers.

LSE

The LSE is powered by an external 32.768 KHz clock. This provides a method of providing a low speed accurate clock for the real time clock.

System and Peripheral Clocks

Once the clock source has been selected it is necessary to configure the internal system and peripheral clocks. The internal clocks are:

• System Clock
• Advanced High Performance Bus (AHB)
• Low speed Advanced Peripheral Bus (APB1)
• High speed Advanced Peripheral Bus (APB2)

Each of these clocks can be scaled using prescalers. A fuller picture of the types of clocks and their relationships can be found in the STM32 Reference Manual (RM0090).

System Clock

The system clock is used to determine the speed at which instructions are executed and has a maximum speed of 168MHz.

Advanced High Performance Bus (AHB)

Derived from the system clock, this bus has a maximum speed of 168MHz.

Low speed Advanced Peripheral Bus (APB1)

Derived from AHB, this bus has a maximum speed of 42MHz.

High speed Advanced Peripheral Bus (APB2)

Derived from AHB, this clock has a maximum frequency of 84MHz.

Non-System Clock Peripherals

A number of the peripheral clocks are not derived from the system clock but have their own independent source.

USB OTG FS, Random Number Generator and SDIO Clock

These clocks are all driven by an independent output of the PLL. The maximum speed for these peripherals is 48MHz.

I2S

The I2S peripherals have their own internal clock (PLLI2S). Alternatively, this can be derived by an independent external clock source.

USB OTG HS and Ethernet Clock

These clocks are derived from an external source.

Microcontroller Clock Output

The STM32 provides the ability to output up to two clocks to the external circuit using the Microcontroller Clock Output (MCO) pins. Both of the outputs can have a prescaler applied. This can be in the range 1 to 5 inclusive.

Microcontroller Clock Output 1 (MCO1) is output on pin PA8. MCO1 output can be one of HSI, LSE, HSE or PLL scaled appropriately.

Microcontroller Clock Output 2 (MCO2) is output on pin PC9. MCO2 output can be one of HSE, PLL, System Clock or PLLI2S scaled appropriately.

The clock output is configured by selecting the appropriate alternative function for the GPIO port and is restricted to 100MHz.

Configuring the Clock

The number of features on the STM32F4 analysis and discussion of the registers and their function large. Luckily ST have come to the rescue and provided a configuration tool to help.

ST Clock Configuration Tool in Wizard Mode

This Excel spreadsheet can be run in both Expert and Wizard mode making it suitable for a wide range of users.

ST Clock Configuration Tool in Expert Mode

The grey number in the above illustration have been calculated whilst the numbers in black can be changed by the users.

The output from this spreadsheet is a source file (system_stm32f4xx.c) which can be added to your project. This file, system_stm32f4xx.c, contains three methods which can be called to setup the clocks on the microcontroller:

• SystemInit – Setup the system including the clocks
• SystemCoreClockUpdate – Setup the SystemCoreClock variable (clock frequency)
• SetSysClock – Setup the system clock (called from SystemInit)

We can see the effect of calling SystemInit by using the code from the simple GPIO example to the following:

#include "stm32f4xx_rcc.h"
#include "stm32f4xx_gpio.h"
#include "system_stm32f4xx.h"

int main()
{
    //
    //  Uncomment this line to see the effect of
    //  the clock change.
    //
	//SystemInit();
    //
    //  Initialise the peripheral clock.
    //
    RCC->AHB1ENR |= RCC_AHB1Periph_GPIOD;
    //
    //  Initialise the GPIO port.
    //
    GPIOD->MODER |= GPIO_Mode_OUT;
    GPIOD->OSPEEDR |= GPIO_Speed_100MHz;
    GPIOD->OTYPER |= GPIO_OType_PP;
    GPIOD->PUPDR |= GPIO_PuPd_NOPULL;
    //
    //  Toggle Port D, pin 0 indefinitely.
    //
    while (1)
    {
        GPIOD->BSRRL = GPIO_Pin_0;
        GPIOD->BSRRH = GPIO_Pin_0;
    }
}

If we run the code above with the SystemInit line commented out and hook an oscilloscope up to pin 0 of port D we get a square wave output with a frequency of about 1.5MHz.

STM32F4 Output (1.46MHz)

Now uncomment the SystemInit line of code and re-run the example. This time we see that the output signal has a frequency of nearly 4.9MHz.

STM32F4 Output (5.75MHz)

Turning the configuration tool into expert mode and tweaking a few of the parameters allows the frequency of the output signal to go to 8.77MHz.

STM32F4 Output (8.77MHz)

Timings are based upon the optimisation level being set to no optimisation. Turning the optimisation on to the maximum speed allows an output signal of nearly 20MHz to be generated.

Conclusion

The STM32 contains a variety of clock sources and configuration using the registers within the microcontroller would be a complex task. The Clock Configuration tool eases the configuration of the internal and peripheral clocks generating the source code for system_stm32f4xx.c automatically.

The Clock Configuration tool and the associated guide can be downloaded from ST’s web site. The tool and document are in the following files:

• stsm-stm32091 Clock Configuration Tool
• AN3988 Clock Configuration Tool User Guide

A few weeks ago I published two articles on development environments for the STM32F4 Doscovery Board. Since then I have become aware of CooCox IDE. This is a small development environment for a number of Microcontrollers including some of the STM32 range of processors.

The IDE promises to be free, unrestricted and simple offering the ability to develop high-quality software solutions in a timely and cost effective manner.

Too good to be true?

Let’s find out.

Web Site

I must admit, it took me a long time to take this tool seriously. I found the web site in the very early days in my search for a reasonable cost development environment for the STM32F4 Discovery board. The look and feel of the site left me a little cold. The design looks like it was put together in the early 1990s.

My only hope was that the tools were better.

Clicking through to the CoIDE page promised to show a video instead I found myself presented with a large amount of white space where the video should be. Maybe this works with IE or Firefox but not with Chrome. If you do see the white spave please take the time to scroll to the bottom of the page. There you will find tables detailing the supported chips/boards along with some download links.

On the whole this web site left me feeling nervous and I must admit that the first time I came across this tool I dismissed it purely based upon the look and feel of the web site.

So what made me come back, a comment made by a colleague, i.e. it worked and was simple to use.

Software

In order to use this IDE to develop applications for your board you also need to download the ARM GCC 4.7 toolchain. This is the same toolchain I used when setting us Eclipse to work with the STM32F4 Discovery board (see Setting up GCC for the STM32F4 Discovery Board). I was lucky enough to have this toolchain already installed making one less task to perform.

Downloading the IDE is simple although you do need to register on the site.

Installation was painless and the initial setup was also simple.

I’m starting to get over the feeling of unease I experienced when I first visited the web site.

Starting the IDE present you with a very familiar look and feel:

New Project

It feels like Eclipse.

Creating a Project

Let’s see how good the environment is by taking the code from STM32 – Simple GPIO and Some Flashing LEDs post.

Creating a new project is simple, just head over to the Project->New Project menu item. Doing this will present you with a wizard which will take you through the steps required to select your board and create an empty project.

Some hints:

• When creating a new project you need to untick the Use default path option if you want your code to be put anywhere other than under the installation directory.
• The select board or chip does not have an option for the STM32F4 Discovery Board (or any for the Discovery boards for that matter). To use this board select Chip and then locate the STM32F407VG chip.

Upon completion of the wizard you will be presented with the component selection tab in the IDE:

Component Selection

This tab is really powerful and makes it easy for the new comer to this board to get off the ground. In the previous example I used two sets of definitions; Reset and clock control and GPIO. Ticking the RCC option in the component tab automatically adds the headers and source files needed to use the RCC library to the project. It also adds any dependencies, in this case the CMSIS core system startup files. After selecting the RCC and GPIO components the IDE looks as follows:

Initial Component Selection

Opening file explorer on the PC showed that the directory structure had been modified and the files put in place. So what happens if you untick and option? Removing components removes the files from the project and it also removes them from file store as well.

Now this feature may seem simple but for the beginner it is really powerful. It ensures that all of the source and header files required are added to the project. This is something which whilst not difficult can trip up the beginner. It is also a little tedious to do with IAR and Eclipse.

One downside of the component selection tab is that it does not easily allow you to remove the source code for the components you have added without also removing the header files as well. I am following the principle of The Way of the Register and not using the Standard Peripheral Library. This requires the header files but not the source code for the library itself. We can only hope the linker is smart enough to remove unused code from the final object executable.

Building the project is as simple as clicking on the Build icon (or using the Project->Build menu item). A few seconds later I have the default applicaiton and the library files compiled.

Debugging

An IDE is really nothing without a reasonable debugger. I remember from the work I did setting up Eclipse (see Setting up GCC for the STM32F4 Discovery Board) that Eclipse needed the OpenOCD library in order to be able to debug an application using ST-Link. There is no mention of OpenOCD when using CooCox. The only additional software required for debugging appears to be the ST-Link USB driver. Again, I already have this installed but you may need to visit ST’s web site for the latest version.

In order to debug we need some code so let’s borrow the code from the Simple GPIO example:

#include "stm32f4xx_rcc.h"
#include "stm32f4xx_gpio.h"

int main()
{
    //
    //  Initialise the peripheral clock.
    //
    RCC->AHB1ENR |= RCC_AHB1Periph_GPIOD;
    //
    //  Initialise the GPIO port.
    //
    GPIOD->MODER |= GPIO_Mode_OUT;
    GPIOD->OSPEEDR |= GPIO_Speed_25MHz;
    GPIOD->OTYPER |= GPIO_OType_PP;
    GPIOD->PUPDR |= GPIO_PuPd_NOPULL;
    //
    //  Toggle Port D, pin 0 indefinitely.
    //
    while (1)
    {
        GPIOD->BSRRL = GPIO_Pin_0;
        GPIOD->BSRRH = GPIO_Pin_0;
    }
}

Starting the debugger (Ctrl-F5) changes the IDE context and presents the debugging interface with the application stopped at the first line of code:

CooCox debugging aspect

Warning – the above image is large

Pressing F5 runs the application to the next breakpoint. As I have not set any breakpoints this should run the application indefinitely and indeed it does. Hooking up the scope to pin 0 of port D shows the following output:

Scope output

Single stepping is achieved using F10 and F11. So re-running the application and pressing F10 should single step over the current line of code and indeed it does. The registers window also highlights the ARM registers that were changed by executing the last instruction:

Register View

One thing that I have found missing which I really appreciate with IAR is the ability to view the state of the peripheral registers (as opposed to the microcontroller registers). This is a really useful feature as it means you do not have to locate the registers in memory and decode them yourself.

Conclusion

CooCox IDE is a simple way to get into working with the STM32F4 Discovery board. The power and simplicity of the tool is only let down by the dated look of the web site.

A cracking tool; well worth looking at.

When starting with a new development board I always revisit the fundamentals like GPIO. Doing this helps establish that the development tools are working and gives a basic library for future development. So with this post we will be looking at GPIO on the STM32 Discovery board. When Rediscovering the STM32 Discovery Board I mentioned that I would need to look at using either the standard peripheral library provided by ST or to use a lower level method of controlling the board. After due consideration I have decided to continue with the lower level access. Whilst this may be more effort it does lead to a better understanding of what is actually happening at the low level.

Our objective today will be to toggle a GPIO pin (Port D, pin 0) generating a square wave. The result will be something similar to the Simple GPIO post for the STM8S.

STM32F4 Discovery Board

The STM32F4 Discovery board is a low cost development board for hobbyists, beginners and experienced users. The board uses the STM32F407VGT6 and hosts a number of sensors including digital accelerometer, push buttons, microphone and DAC. It also contains four built in LEDs which can be used to give feedback to the developer and breakout pins for the GPIO ports.

STM32F4 Discovery Board

Each of the GPIO pins can be used for simple input/output of digital signals. The majority of the pins are also mapped to one or more alternative functions. For instance, Port C, pin 3 is also mapped to the following alternative functions:

• SPI2 MOSI
• I2S2 SD
• OTG HS ULPI NXT
• ETH MI TX Clk
• EVENTOUT

For the remainder of this post we will restrict ourselves to the GPIO functionality of the chip and demonstrate the following:

• Output a digital signal on a single GPIO pin
• Flash one of the LEDs on the board

The alternative functionality will be considered in future posts.

The functionality of the 16 pins on each of the GPIO ports is controlled by a number of registers. The description of each of the registers can be found in RM0090 Reference Manual for the STM32 chip. This manual can be downloaded from STs web site.

GPIO Registers

Each STM32 chip has a number of ports each of which has 16 pins. As already noted, each of these pins has a number of functions, the most basic of which is digital input/output. The functionality and state of each port is controlled by a number of GPIO registers:

• Four configuration registers
• Two data registers
• One set/reset register
• One locking register
• Two alternative function registers

An overview of the registers follows; a fuller description of the registers can be found in section 7 of RM0090 Reference Manual (Revision 4).

When referring to the registers, the reference manual uses the following notation:

GPIOx_Function

Where x is replaced by the port to be used. For instance, GPIOx_MODER refers to the generic mode register for a GPIO port. A specific instance of this would be GPIOD_MODER. This refers to the mode register for port D. Normally, x is in the range A to I and is defined by the specific version of the STM32 being used in the project.

Configuration Registers

The STM32 has four configuration registers for each of the ports.

• Port mode register – GPIOx_MODER
• Output type register – GPIOx_OTYPER
• Speed register – GPIOx_OSPEEDR
• Pull-up/Pull-down register – GPIOx_PUPDR

Each of these registers is 32-bits wide although not all of the bits are used in all of the registers.

Port Mode Register – GPIOx_MODER

This 32 bit register holds 2 bit values which defines the operation mode. The modes allowed are:

In general, the default reset value for this register is 0. Some of the ports are reset to non-zero values as the pins in the port have special meanings (debugging pins etc). The rest values are:

The bits in the register are read/write and are in consecutive pairs. So bits 0 & 1 define the mode for pin 0, bits 2 & 3 define the mode for pin 1 etc.

Output Type Register – GPIOx_OTYPER

This is a 32-bit register but only the lower 16 bits are used. The top 16 bits are reserved and should not be used. This register uses a single bit for each pin to define the output type of the pins in the port. So, bit 0 defines the output type for pin 0, bit 1 for pin 1 etc.

Speed Register – GPIOx_OSPEEDR

This 32-bit register uses all of the bits in the register in pairs (similar to the port mode register). The bits define the output speed of the port. The bit pairs have the following meaning:

The reset value for these registers is 0x0000 00C0 for port B and 0x0000 0000 for all other registers.

Pull-up/Pull-down register – GPIOx_PUPDR

This 32-bit register uses all of the bits in the register in pairs (similar to the port mode register). The bits define pull-up / pull-down resistor mode for the pins on a port. The bit pairs have the following meaning:

The reset values for the registers are:

Data Registers

The two data registers for each port indicate the input/output state of the port. Each of the registers are 32-bit registers but only the lower 16 bits are used. The top 16 bits are reserved and should not be used.

• Input data register – GPIOx_IDR
• Output data register – GPIOx_ODR

Input data register – GPIOx_IDR

The input data register indicates if a high or low signal has been applied to the pin within a port. The register is read-only and the whole word should be read.

As with the output type register – GPIOx_OTYPER, the bits in the register map onto the pins in the port (bit 0 maps to pin 0, bit 1 to pin 1 etc.).

The reset value for all of these registers is 0x0000 XXXX where X indicates that the bits are unknown as they will be defined by the input signals applied to the pins are reset.

Output data register – GPIOx_ODR

The output data register allows the program to change the output state of a pin within the port. This is a 32-bit register and only the lower 16 bits are used. The top 16 bits are reserved and should not be used. The output states are defined as:

As with the output type register – GPIOx_OTYPER, the bits in the register map onto the pins in the port (bit 0 maps to pin 0, bit 1 to pin 1 etc.). The bits in the lower 16 bits of the register are all read/write bits.

The reset value for all of these registers is 0x0000 0000.

A more effective way of setting/resetting a bit in the output register is to use the bit set/reset register.

Set/reset register

The set/reset register sets or resets a single bit in the output data register.

Bit Set/Reset Register – GPIOx_BSSR

This is a 32-bit register and it is split into two halves, the lower 16 bits are used for setting a bit and the upper 16 bits are used for resetting a bit. This is a write only register; reading this register will return 0x0000.

Setting a bit in the lower 16-bits of this register will cause the corresponding bit in the output data register to be set to 1.

Similarly, setting a bit in the upper 16-bits of this register will cause the corresponding bit in the output data register to be set to 0.

For the lower 16-bits the mapping is simple, bit 0 in GPIOx_BSRR maps to bit 0 in GPIOx_ODR etc. For the upper 16-bits, bit 16 of the GPIOx_BSRR maps to bit 0 of the GPIOx_ODR; bit 17 of GPIOx_BSRR maps to bit 1 of GPIOx_ODR etc.

So why provide the set/reset functionality when you have the output data registers? The set/reset register provide an atomic method of setting or resetting an output pin on a port. When using the output data registers, the compiler will have to generate a number of statements in order to set or reset a pin. This can allow an interrupt to be processed when part way through the set/reset operation. By using this register it is possible to set or reset a pin using a single instruction. This means that the operation will complete before the interrupt can be processed.

Configuration Lock Register

This register is used to lock the configuration of the port until the next reset of the chip.

Configuration Lock Register – GPIOx_LCKR

The register is a 32-bit register but only 17 bits are actually used. The lower 16 bits indicate which bit of the port configuration is locked. So setting bit 0 of the register will lock the configuration of pin 0 etc.

The final bit used is bit 16 in the register (known as the Lock Key – LCKK); this bit determines the lock status of the port; a zero indicates that no lock is applied whilst a 1 indicates that the port configuration is locked.

In order to lock the configuration of a port the configuration lock write sequence must be followed. This will prevent accidental locking of the port configuration. The algorithm for locking the configuration is as follows:

• Set bits 0 through 15 of the register indicating which pins should have their configuration locked
• Set LCKK to 1 and write the value into the register
• Set LCKK to 0 and write the value into the register
• Set LCKK to 1 and write the value into the register
• Read the lock bit of the port

It is important to note that the values in bits 0 through 15 should not change whilst following the above sequence. Should they change or any error occur then the lock will be aborted.

The final step, reading the lock bit, confirms the success or failure of the operation.

Alternative function registers

The alternative function registers allow the configuration of the port to change from simple GPIO to an alternative function such as SPI MOSI. These registers are noted here but will not be discussed further as they will be covered in subsequent posts.

C Definitions and Some Typedefs

The register in the STM32 microcontroller have been mapped onto specific memory locations within the valid address space of the STM32. These memory locations are defined in the various header files for the microcontroller. For instance, the following type definition has been taken from the header file stm32f4xx.h:

typedef struct
{
  __IO uint32_t MODER;    /*!> GPIO port mode register,               Address offset: 0x00      */
  __IO uint32_t OTYPER;   /*!> GPIO port output type register,        Address offset: 0x04      */
  __IO uint32_t OSPEEDR;  /*!> GPIO port output speed register,       Address offset: 0x08      */
  __IO uint32_t PUPDR;    /*!> GPIO port pull-up/pull-down register,  Address offset: 0x0C      */
  __IO uint32_t IDR;      /*!> GPIO port input data register,         Address offset: 0x10      */
  __IO uint32_t ODR;      /*!> GPIO port output data register,        Address offset: 0x14      */
  __IO uint16_t BSRRL;    /*!> GPIO port bit set/reset low register,  Address offset: 0x18      */
  __IO uint16_t BSRRH;    /*!> GPIO port bit set/reset high register, Address offset: 0x1A      */
  __IO uint32_t LCKR;     /*!> GPIO port configuration lock register, Address offset: 0x1C      */
  __IO uint32_t AFR[2];   /*!> GPIO alternate function registers,     Address offset: 0x20-0x24 */
} GPIO_TypeDef;

This header file can be found in the Standard Peripheral Library as supplied by ST Microelectronics.

A careful examination of the members of the struct within the typedef reveals that with one exception, the members of the struct all map directly onto the registers we have been discussing above. The one exception is the BSSR register. This has been split into two components BSSRL and BSSRH. This split nicely maps to the difference in functionality of the two halves of the register, namely Setting and resetting of individual bits in the output data register.

Locating A GPIO in Memory

Once we have the layout of the registers (as defined in the struct above), we simply need to map the structure onto the right location in memory. A little further digging in the header file leads us to the following #define statements:

#define GPIOD             ((GPIO_TypeDef *) GPIOD_BASE)

#define GPIOD_BASE        AHB1PERIPH_BASE + 0x0C00)

#define APB1PERIPH_BASE   PERIPH_BASE

#define PERIPH_BASE       ((uint32_t) 0x40000000) /*!< Peripheral base address in the alias region                                */

Following the chain of #define statements leads us to the the conclusion that the registers for GPIOD are located at memory location 0x40000C000. These definitions mean that we should be able to access individual registers with statements such as:

GPIOD->MODER = 0x01;    // Set Pin 0 of Port D to input.

A Practical Demonstration

After all this theory we must be ready for some coding. In this section we will look at creating two small applications:

• GPIO Toggle – toggling a single pin on a GPIO port
• Blinky – Flashing a single LED

The first of the two applications will simply toggle a single GPIO pin as fast as possible using the default reset state of the microcontroller. Note that an oscilloscope will be required in order to prove that the application is working correctly

The second application will make use of the on board LEDs. This will require a little more coding in order to provide a delay between turning the LED on and off in order to make the flashing visible to the naked eye.

Application 1 – Toggling A GPIO Pin

This application is simple and consists of two parts:

• Initialisation
• A loop which toggles the GPIO pin

The full application looks like this:

#include "stm32f4xx_rcc.h"
#include "stm32f4xx_gpio.h"

int main()
{
    //
    //  Initialise the peripheral clock.
    //
    RCC->AHB1ENR |= RCC_AHB1Periph_GPIOD;
    //
    //  Initilaise the GPIO port.
    //
    GPIOD->MODER |= GPIO_Mode_OUT;
    GPIOD->OSPEEDR |= GPIO_Speed_25MHz;
    GPIOD->OTYPER |= GPIO_OType_PP;
    GPIOD->PUPDR |= GPIO_PuPd_NOPULL;
    //
    //  Toggle Port D, pin 0 indefinitely.
    //
    while (1)
    {
        GPIOD->BSRRL = GPIO_Pin_0;
        GPIOD->BSRRH = GPIO_Pin_0;
    }
}

One thing to note from the above code is that we need to initialise the peripheral clocks (this should be taken as read for the moment and will be covered in future posts). When initialising the GPIO port we should take into consideration the default clock speed of the Discovery board after reset. By default this is 8 MHz and so we should set the speed of the output port accordingly. This leads to a configuration for pin 0 of output with a maximum speed of 25 MHz, push pull with not pull-up or pull-down resistors.

Once initialised we enter the main program loop. Here the application uses the set/rest registers to toggle pin 0. This shows how the 32-bit register is split into two, one for the set and one for the reset operation.

If we create a simple STM32 project using IAR, compile and then deploy this application we get the following output on the oscilloscope:

STM32 Scope Output

And there we have it, our first application deployed to the STM32 Discovery board.

Blinky – Flashing A Single LED

This second example is really aimed at those who do not have access to an oscilloscope. Here we will slow down the output of the GPIO port and flash one of the built in LEDs.

The STM32F4 Discovery board has four built in LEDs which can be accessed by setting/resetting pin 12 through 15 on port D. The LED colours are:

Using the code in the previous example as a starting point we find ourselves with an application which looks something like this:

#include "stm32f4xx.h"
#include "stm32f4xx_gpio.h"
#include "stm32f4xx_rcc.h"

#define LED_GREEN      12
#define LED_ORANGE     13
#define LED_RED        14
#define LED_BLUE       15

int main()
{
    int pin = LED_RED;
    uint32_t mode = GPIO_Mode_OUT << (pin * 2);
    uint32_t speed = GPIO_Speed_100MHz << (pin * 2);
    uint32_t type = GPIO_OType_PP << pin;
    uint32_t pullup = GPIO_PuPd_NOPULL << (pin * 2);
    //
    //  Initialise the peripheral clock.
    //
    RCC->AHB1ENR |= RCC_AHB1Periph_GPIOD;
    //
    //  Initilaise the GPIO port.
    //
    GPIOD->MODER |= mode;
    GPIOD->OSPEEDR |= speed;
    GPIOD->OTYPER |= type;
    GPIOD->PUPDR |= pullup;
    //
    //  Toggle the selected LED indefinitely.
    //
    int index;
    while (1)
    {
        GPIOD->BSRRL = (1 << pin);
        for (index = 0; index < 500000; index++);
        GPIOD->BSRRH = (1 << pin);
        for (index = 0; index < 500000; index++);
    }
}

Deploying this application should flash the selected LED just below the STM32 microcontroller on the STM32F4 Discovery board.

Conclusion

This post presented two simple applications which toggle GPIO lines on Port D. Using these techniques and the additional information in the register descriptions you should be able to extend the application above to control digital devices such as shift registers etc.

A few days ago I wrote this post about the STM32 Discovery board and my experiences setting this board up with the IAR Embedded Workbench Kickstarter for ARM. In that post I mentioned that there are some free development tools available for this board, namely the GCC tool chain. I was going to leave these tools until I reached the point where I needed to remove the code size restriction which is in place for the IAR toolset.

Well I could not resist investigating this tool chain further.

Installing the Software

A quick visit to Google lead me to Hussam Al-Hertani’s blog where there are a number of articles which discuss setting up the GCC tool chain for the STM32F0 Discovery board. These three articles provide a comprehensive overview of the steps you need to follow:

• Part 1 – Setting up the GCC ARM Toolchain
• Part 2 – Setting up the Eclipse IDE
• Part 3 – Setting up Debugging with the Eclipse IDE (OpenOCD 0.6.x)

Also included on the blog is an overview of the GCC compilation process.

The two boards (STM32F0 and STM32F4) should be similar and so I decided to give the above a go and see if I could use the GCC tools with the STM32F4 Discovery board.

Installing the Tools

The installation process went reasonably well with only a couple of issues.

Part 1 – Setting up the GCC ARM Toolchain

The installation of the tools went according to the blog until we reached the instructions to compile the sample application. The main problem here was that the application would not compile due to missing header files. This problem was caused by the differences in the directory names and structure of the firmware libraries. The only changes required were to the include and library variables in the makefile.

Part 2 – Setting up the Eclipse IDE

Setting up Eclipse was completed without any issues.

Part 3 – Setting up Debugging with the Eclipse IDE (OpenOCD 0.6.x)

Setting up OpenOCD and connecting this to Eclipse was also straightforward.

Creating A New Example

Remember this code:

GPIO_InitTypeDef  GPIO_InitStructure;

RCC_AHB1PeriphClockCmd(RCC_AHB1Periph_GPIOD, ENABLE);
int flag = 0;
GPIO_InitStructure.GPIO_Pin = GPIO_Pin_0;
GPIO_InitStructure.GPIO_Mode = GPIO_Mode_OUT;
GPIO_InitStructure.GPIO_OType = GPIO_OType_PP;
GPIO_InitStructure.GPIO_Speed = GPIO_Speed_100MHz;
GPIO_InitStructure.GPIO_PuPd = GPIO_PuPd_NOPULL;
GPIO_Init(GPIOD, &GPIO_InitStructure);
while (1)
{
    if (flag)
    {
        GPIO_SetBits(GPIOD, GPIO_Pin_0);
        flag = 0;
    }
    else
    {
        GPIO_ResetBits(GPIOD, GPIO_Pin_0);
        flag = 1;
    }
}

In order to generate a new example we start with the code we have compiled and working. There are very few changes required. Theses are main made in the make file. We remove the files which are not required and then verify that the libraries and include files can be accessed by the compiler.

The final change is to replace the code in main.c with our code above.

Compilation and deployment from within Eclipse went as expected and the application ran with no issues.

How About Debugging?

With Eclipse open and the above project loaded I set a breakpoint on the first line of the application. Starting the debugger stopped the application at the first line of code – things are looking good. Single stepping also appeared to look as though it was working well at first. A few lines further on and this is where the issues started. The debugger and the line of source code started to get out of step. The IDE would skip a line of code in a consistent manner. It looks like the debugger information is slightly out of sync with the breakpoints. After spending a little time looking at this I found that the original makefile I have been using had the optimisation level set to -Os. The debugger/IDE started to behave as expected when I changed this to -O0.

Conclusion

The installation of the GCC development environment was simple enough and the instructions on Hertaville are comprehensive and well worth visiting. It is always good to have a free unlimited development environment.

Change Log:

• 10th March 2013: Added additional information about the optimisation flag in the build file.

About a year ago I started to look at alternatives to the Netduino boards and came across the STM32 Discovery board. I spent a little time with this board and wrote a simple application which toggled a GPIO pin – the electronic equivalent of Hello, world. I have had very little time to spend with this board since then but now I feel it is time to revisit the STM32 having spent some time cutting my teeth on the STM8S.

Development Tools

I’m a hobbyist and this means I do not have a vast amount of money to spend on development tools and equipment. A quick survey of the market gives a few options for development tools (software). The prices put the majority if these out of the question for the home developer who does not intend to recover the costs. There are still a number of options open to us by using the restricted versions of the professional tools. Several of the major players have released limited editions of the full development suite. The normal seems to be restricting the amount of code the development environment can deal with before you are required to purchase the software. I have had a look at the following tools (presented in no particular order) over the past few days:

• Atollic TRUEStudio
  Free Lite edition with a code restriction of 32K on the Cortex-M4
• IAR Embedded Workbench
  Free kick starter edition available with a code limit of 32K
• Keil MDK
  No free version seems to be available and the site has a Quote button but no pricing.
• GNU C/C++ with Eclipse IDE
  Free with no code restriction
• TASKING
  No free edition available

A 32K code restriction does not seem unreasonable for the hobbyist so I decided to start with the IAR Kickstarter edition as I had a really good experience with the STM8S Kickstarter edition of the same development environment. I suppose the major driver was the fact that I will not have to learn a whole new series of key strokes in order to compile/debug as the IDE is the same as the STM8S version of the software which I have been using for nearly a year now.

Installation

Installation of the development environment was simple. The setup weighs in at a hefty 913 MBytes. Running the setup was painless and took only a few minutes.

Testing the installation

To test the deployment I decided to compile one of ST’s own example applications. These can be found in the firmware package which can be downloaded from ST’s web site. At the time of writing the latest version of the firmware was version 1.1.0. When you unzip the firmware you will find a Project directory which contains a number of samples including a Demonstration example. If you open this directory you will find a number of sub directories containing the projects for the various development tools available. We are interested in the EWARM directory as this contains the IAR project.

Opening the workspace STM32F4-Discovery_Demo.eww, compiling and deploying the application was simple. Just make sure that you have the STM32 Discovery board plugged into your computer using a mini USB connector through CN1 on the board.

Once deployed the IDE will halt program execution just before the main method is called. Pressing F5 will start the application running. At this point you should see the LEDs on the main board light up in a chase style pattern.

Template Application

The demonstration example shows how to use many of the development board features including the sensors, sound generation and the USB capabilities. The application therefore contains a number of features which we will/may not be using in our applications. I decided to strip the code down to a very basic application which can be used as a starting point for future application development. In order to prove that the template work and that we have not removed too much code we will recreate the previous application which toggled a GPIO pin.

There is a certain amount of startup code required in order to configure the STM32 and put it into a state where is can run an application. The code for this appears to be in the following files within the project:

• startup_stm32f4xx.s
• stm32f4xx_it.c
• system_stm32f4xx.c

The code in these file set up the interrupt tables and system clocks before passing control the main.

In order to ensure that I took as much of the configuration as possible over from the demonstration program I started with a copy of the contents of the entire directory and then started to remove files. Doing this would ensure that the project options were preserved.

To see some output we will need to add some code to output a signal on the scope. This application will toggle pin 0 on port D in a loop. The main program becomes:

GPIO_InitTypeDef  GPIO_InitStructure;

RCC_AHB1PeriphClockCmd(RCC_AHB1Periph_GPIOD, ENABLE);
int flag = 0;
GPIO_InitStructure.GPIO_Pin = GPIO_Pin_0;
GPIO_InitStructure.GPIO_Mode = GPIO_Mode_OUT;
GPIO_InitStructure.GPIO_OType = GPIO_OType_PP;
GPIO_InitStructure.GPIO_Speed = GPIO_Speed_100MHz;
GPIO_InitStructure.GPIO_PuPd = GPIO_PuPd_NOPULL;
GPIO_Init(GPIOD, &GPIO_InitStructure);
while (1)
{
    if (flag)
    {
        GPIO_SetBits(GPIOD, GPIO_Pin_0);
        flag = 0;
    }
    else
    {
        GPIO_ResetBits(GPIOD, GPIO_Pin_0);
        flag = 1;
    }
}

In order to use the GPIO pins we need to compile in the GPIO standard library. Specifically stm32f4xx_gpio.c and stm32f4xx_rcc.c. These are probably better added as a group so we add a group and then the files. This will leave the project structure looking something like the following:

Compiling the application gave a missing method/preprocessor directive, namely assert_param. I have come across this in the past. This method validates the parameters passed into the methods in the standard library methods. A quick addition of the following to main.h should make the code compile:

void assert_param(void *x) {}

Compile this and we get a whole lot of errors but at least it compiles. Strictly speaking this needs resolving but I still have to decide if long term I will be using the standard library or if I will be following another path. I remember getting burned by the STM8S version of the library. A decision for another day, for now I’ll continue with the template and the test application.

Saving all of this and then running the program with the scope hooked up to Port D, Pin 0 gives the following output on the scope:

My only concern was the frequency of the output. The processor is supposed to be running at 168 MHz. I would have expected something higher than the 417 Khz I was getting.

A quick delve into the standard library and we find that the code which sets and resets the GPIO stat is actually simple. There are the mandatory calls to the assert_param method/preprocessor directive followed by a simple setting of a value. We can substitute the calls in the main loop with the actual code. The main loop now looks something like this:

while (1)
{
    if (flag)
    {
        GPIOD->BSRRL = GPIO_Pin_0;
        flag = 0;
    }
    else
    {
        GPIOD->BSRRH = GPIO_Pin_0;
        flag = 1;
    }
}

Deploying and running this application gives a lot more respectable output:

As you can see, we are getting a little over 4.1 MHz.

Conclusion

I now have a small template STM32 project which I can call upon at any time to give me a starting point for development with the STM32 Discovery board. I still need to work on the assert_param issue but only if I am to carry on working with the standard library.

If you are interested in using this template then feel free to download the code. You may need to make some adjustments to the default paths for the include directories. To do this:

• Right click on the project name (Test STM32 – Debug)
• Select Options…
• Now select C/C++ Compiler
• Scroll to the right until you find the Preprocessor tab
• Enter the paths for your include directories

A new year, a new journey. Let’s see where this takes us.

A few days ago in the Netduino chat room we were discussing a problem with the Timer class. Should be a simple problem to solve as I had used timers in .NET applications many times. A short while later it became obvious that the Timer class was not as easy to use as I thought. In this post we will look at the NETMF implementation of the Timer class and how it can be used.

In all of the examples below I will be working on a 50% duty cycle. So a 100 Hertz signal should be 10ms between the rising edges of the signal where the signal will be high for 5ms followed by low for 5ms.

All of the following examples will run on the Netduino Plus 2.

Setting up a Simple Timer

The basic timer constructor takes four parameters:

• Callback
• User defined object
• Delay
• Period

Callback

The Callback parameter is a TimerCallback object. This will be called by the Timer at the period defined by the period parameter.

User defined object

This is an object defined by the user and can be used to identify the source of the callback. Initially we will be setting this to null as we will not be using it.

Delay

The number of milliseconds to pause before the callback method is called.

Period

Period (in milliseconds) between invocations of the Callback method.

So now we know how this should work, let’s jump in with a simple example. Here we will generate a 100Hz signal and we will start the timer immediately. The code for this will look like this:

using System;
using System.Threading;
using Microsoft.SPOT.Hardware;
using SecretLabs.NETMF.Hardware.Netduino;

namespace BasicTimer
{
    public class Program
    {
        private static Timer oneHundredHertzTimer = null;
        private static OutputPort oneHundredHertzPulse = null;
        private static TimerCallback timerCallback = null;
        private static OutputPort trigger = null;

        public static void Main()
        {
            trigger = new OutputPort(Pins.GPIO_PIN_D1, false);
            timerCallback = new TimerCallback(TimerInterrupt);
            oneHundredHertzPulse = new OutputPort(Pins.GPIO_PIN_D7, false);
            trigger.Write(true);
            trigger.Write(false);
            oneHundredHertzTimer = new Timer(timerCallback, null, 0, 5);
            Thread.Sleep(Timeout.Infinite);
        }

        private static void TimerInterrupt(object state)
        {
            oneHundredHertzPulse.Write(!oneHundredHertzPulse.Read());
        }
    }
}

The trigger pin is simply used to indicate the start of the program run. This is used to allow the logic analyser to start data capture.

If we hook up the logic analyser we should get a trace which looks something like the following:

Basic Timer

The top trace shows the trigger pulse whilst the trace below shows the output from the timer callback. If we expand the start of the trace we see the following:

Timer with trigger

As you can see, there is a small pulse (the trigger) at the start followed by the pulses generated by the timer. The timer between the falling edge of the trigger and the rising edge of the first pulse generated by the timer is approximately 16us. This can be put down to the amount of time it takes for the NETMF instructions to complete the construction of the timer. So the first thing the timer does is to invoke the callback method defined in the constructor.

If we modify the construction of the timer slightly we can see the impact of the delay parameter. Let’s change the construction to the following:

oneHundredHertzTimer = new Timer(timerCallback, null, 50, 5);

If we run this application (see the project BasicTimerWithDelay) we will see the following in the logic analyser:

As you can see, the start of the timer has been delayed by 50ms.

Two Timers, One Interrupt

In this example we will look at the role the user defined object has in the TimerCallback parameter. This object can be used to allow the system to use a single callback from multiple timers. The object can be used to determine which timer invoked the callback.

The user defined object is an instance of an object which is passed to the callback method when it is called. In the following we start with an enum:

private enum TimerState { OneHertz, TwoHertz };

Now when we create the timers we create a new object and pass this into the constructor. Our constructors look like the following:

TimerState oneHertzState = TimerState.OneHertz;
oneHertzTimer = new Timer(timerCallback, oneHertzState, 0, 500);

TimerState twoHertzState = TimerState.TwoHertz;
twoHertzTimer = new Timer(timerCallback, twoHertzState, 0, 250);

for the two hertz timer.

As you can see, both timers have the same method being invoked as the callback method. However, each timer will pass in a different object (albeit of the same type) to the callback method. We can then use this parameter to determine the action we should take. The code for the callback method will look like the following:

private static void TimerInterrupt(object state)
{
	switch ((TimerState) state)
	{
		case TimerState.OneHertz:
			oneHertzPulse.Write(!oneHertzPulse.Read());
			break;
		case TimerState.TwoHertz:
			twoHertzPulse.Write(!twoHertzPulse.Read());
			break;
	}
}

The full application is as follows:

using System;
using System.Threading;
using Microsoft.SPOT.Hardware;
using SecretLabs.NETMF.Hardware.Netduino;

namespace TimerExample
{
    public class Program
    {
        private static Timer oneHertzTimer = null;
        private static OutputPort oneHertzPulse = null;

        private static Timer twoHertzTimer = null;
        private static OutputPort twoHertzPulse = null;
        
        private static TimerCallback timerCallback = null;

        private enum TimerState { OneHertz, TwoHertz };

        private static OutputPort trigger = null;

        public static void Main()
        {
            trigger = new OutputPort(Pins.GPIO_PIN_D1, false);
            timerCallback = new TimerCallback(TimerInterrupt);
            trigger.Write(true);
            trigger.Write(false);
            //
            //  Set up the one hertz timer.
            //
            oneHertzPulse = new OutputPort(Pins.GPIO_PIN_D7, false);
            TimerState oneHertzState = TimerState.OneHertz;
            oneHertzTimer = new Timer(timerCallback, oneHertzState, 0, 500);
            //
            //  Set up the two hertz timer.
            //
            twoHertzPulse = new OutputPort(Pins.GPIO_PIN_D6, false);
            TimerState twoHertzState = TimerState.TwoHertz;
            twoHertzTimer = new Timer(timerCallback, twoHertzState, 0, 250);
            //
            Thread.Sleep(Timeout.Infinite);
        }

        private static void TimerInterrupt(object state)
        {
            switch ((TimerState) state)
            {
                case TimerState.OneHertz:
                    oneHertzPulse.Write(!oneHertzPulse.Read());
                    break;
                case TimerState.TwoHertz:
                    twoHertzPulse.Write(!twoHertzPulse.Read());
                    break;
            }
        }
    }
}

If we run this application we will see the following on the logic analyser:

Two timers with one interrupt.

As you can see, we are generating a one and a two hertz signal using a single callback.

Stopping A Timer

So far we have considered starting a timer and the various options for delaying and callbacks. There will come a point where we will want to stop a timer from executing. A quick glance through the methods provided for the Timer class reveals that there is no method do do this. In this scenario, the first instinct is to simply set the variable referencing to the object to null.

So if we take the first example as out starting point we will add a small amount of code to deal with a button press. The idea is that when the user presses the onboard button on the Netduino Plus 2, the application will terminate the timer by setting to timer object to null. The code becomes:

using System.Threading;
using Microsoft.SPOT.Hardware;
using SecretLabs.NETMF.Hardware.Netduino;
using Microsoft.SPOT;

namespace StoppingATimer
{
    public class Program
    {
        private static Timer oneHundredHertzTimer = null;
        private static OutputPort oneHundredHertzPulse = null;
        private static TimerCallback timerCallback = null;
        private static InterruptPort button = null;

        public static void Main()
        {
            timerCallback = new TimerCallback(TimerInterrupt);
            oneHundredHertzPulse = new OutputPort(Pins.GPIO_PIN_D7, false);
            button = new InterruptPort(Pins.ONBOARD_BTN, true, Port.ResistorMode.PullUp, Port.InterruptMode.InterruptEdgeHigh);
            button.OnInterrupt += new NativeEventHandler(button_OnInterrupt);
            oneHundredHertzTimer = new Timer(timerCallback, null, 0, 5);
            Thread.Sleep(Timeout.Infinite);
        }

        private static void button_OnInterrupt(uint data1, uint data2, System.DateTime time)
        {
            oneHundredHertzTimer = null;
            Debug.Print("Timer set to null.");
        }

        private static void TimerInterrupt(object state)
        {
            oneHundredHertzPulse.Write(!oneHundredHertzPulse.Read());
        }
    }
}

If you deploy this application to the Netduino Plus 2 you will see the same output (on the logic analyser) as the first example in this post. Namely, a 100Hz square wave with a 50% duty cycle.

So the next thing to try is pressing the button and see what happens. If everything works as expected then the timer should be set to null and the timer should terminate. So let’s press the button and start the logic analyser.

And the timer keeps on running. In order to kill the timer we must ensure that it is disposed of correctly. We can do this by modifying the button interrupt method as follows:

private static void button_OnInterrupt(uint data1, uint data2, System.DateTime time)
{
	oneHundredHertzTimer.Dispose();
	oneHundredHertzTimer = null;
	Debug.Print("Timer set to null.");
}

Running the application again and pressing the button results in the expected behaviour.

Changing the Frequency

In our final example we will look at changing the frequency of the timer. This example uses the button press interrupt from the previous example but this time it will halve the period (i.e. double the frequency of the output signal) of the timer. The application uses the Change method to change the timer on the fly. So let’s dive straight in with some code:

using System.Threading;
using Microsoft.SPOT.Hardware;
using SecretLabs.NETMF.Hardware.Netduino;
using Microsoft.SPOT;

namespace ChangingTheFrequency
{
    public class Program
    {
        private static Timer frequencyGenerator = null;
        private static OutputPort frequencyGeneratorOutput = null;
        private static TimerCallback timerCallback = null;
        private static InterruptPort button = null;
        private static int currentPeriod;

        public static void Main()
        {
            timerCallback = new TimerCallback(TimerInterrupt);
            frequencyGeneratorOutput = new OutputPort(Pins.GPIO_PIN_D7, false);
            button = new InterruptPort(Pins.ONBOARD_BTN, true, Port.ResistorMode.PullUp, Port.InterruptMode.InterruptEdgeHigh);
            button.OnInterrupt += new NativeEventHandler(button_OnInterrupt);
            currentPeriod = 500;
            frequencyGenerator = new Timer(timerCallback, null, 0, currentPeriod);
            Thread.Sleep(Timeout.Infinite);
        }

        private static void button_OnInterrupt(uint data1, uint data2, System.DateTime time)
        {
            if (currentPeriod > 100)
            {
                currentPeriod /= 2;
                frequencyGenerator.Change(0, currentPeriod);
            }
        }

        private static void TimerInterrupt(object state)
        {
            frequencyGeneratorOutput.Write(!frequencyGeneratorOutput.Read());
        }
    }
}

As you can see the code is relatively straight forward. Connecting up the logic analyser and running the application generates a 1 Hz signal (500ms period will result in 1Hz). Pressing the button on the Netduino Plus 2 will cause the period to be halved and hence the frequency to be doubled. You logic analyser will confirm this, I know mine did.

One thing you should note is that the Change method returns a value to indicate if the method has disposed of the old timer. I have never seen this not return true but if you see some odd behaviours with timers still generating interrupts at old frequencies then it may be the result of an old timer still hanging around.

Conclusion

This article was inspired by a posting on the Netduino chatrooms regarding the changing/killing of timers. I must admit I was a little astounded to find that there was no Stop or Start method in the class. As you can see, the techniques for doing this are not complex, they are just not obvious.

There are also some nice feature, like the fact that Timers run in their own threads. Investigation of these features are left as an exercise for the reader.

As always, the Source code is available for download.

In this, the last of the series of posts regarding implementing SPI Slave devices using the STM8S, we will look at building a module for the Netduino Go. This post builds upon the two previous posts:

• STM8S SPI Slave
  A simple SPI implementation using hardware SPI (single byte exchange).
• STM8S SPI Slave (Part 2)
  Software SPI implementation (using buffers to allow the exchange of data packets).

Here we will build upon the buffering and overlay the the Netduino Go 1.0 protocol in order to allow the two devices to communicate. We will also extend the STM8S application to add a simple function table to allow the simple addition of extra functionality to the system.

The makers of the Netduino Go, Secret Labs, have not formally released the GoBus 1.0 specification as a document. They have however release the source code to some of their modules and this can be found in the Wiki. The code found in the Wiki posts along with discussions on various forums has been used in the production of the code presented here. Credit for help is due to Secret Labs for releasing the code and also to the following Netduino forum members:

• Chris Walker
• CW2

These forum members have given assistance in one form or another over the past few months and without their help this post would not have been possible.

GoBus 1.0 Protocol

The early GoBus protocol uses an 18 byte data packet which is exchanged by the Netduino Go and the module. This packet of data contains a one byte header, 16 bytes of data and a one byte checksum with the data packets being exchanged over SPI. With the exception of the header and the checksum it appears that meaning of the data within the 16 byte payload is determined by the module developer.

I would also point the reader to the blog post A Developers Introduction to GoBus by Matt Isenhower on the Komodex System web site.

Enumeration

When the Netduino Go is first powered it will look at each of the Go Sockets in turn and attempt to interrogate the modules which are connected to the main board. It does this by sending out a packet with a single byte header 0xfe followed by 16 data bytes and a checksum. From experience, the data bytes are normally set to 0xff.

The module attached to the socket is then required to respond with a header byte of 0x2a followed by the 16 byte GUID of the module and the checksum byte.

The end result of this exchange is that the Netduino Go will have built up a list of modules attached to the main board along with the corresponding socket numbers.

This process then allows the .NET code to connect to a module using the GUID or the GUID and socket number. Successful connection is indicated by the blue LED by the side of the socket being illuminated. A failed connection normally results in an exception being thrown.

Data Transfer/Module Control

When the code running on the Netduino Go has successfully attached to the module on a socket it can start to control/communicate with the module. At this point it appears that the protocol uses the header 0x80 to indicate transfer between the module and the main board. So our data packets remain 18 bytes with the following format:

• 0x80 – Header
• 16 byte payload
• 1 byte CRC

It appears that the meaning of the 16 byte payload is determined by the module developer.

GPIO Interrupt

The protocol also allows for the use of a single GPIO. This can be used as a signalling line to let either side know that an action is pending. Convention appears to be to use this to allow the module to let the code on the main board know that there is some data/action pending.

A Simple Module

We will be creating a simple module to illustrate how the STM8S and the Netduino code work together. In order to use the least hardware possible the module will perform a simple calculation and return the result. Our module will need to perform the following:

• Enumerate using a GUID allowing the Netduino Go to detect the module
• Receive a number from the Netduino Go
• Perform a simple calculation and notify the Netduino Go that the result is ready.
• Send the result back to the Netduino Go when requested.

This simple module illustrates the key types of communication which may be required of a simple module. It is of course possible to use these to perform other tasks such as controlling a LED or receiving input from a button or keypad.

Netduino Go Module Driver

The Netduino Go code derived from the C# code published by Secret Labs in their Wiki. The major changes which have been made for this post are really concerned with improving clarity (adding comments at each stage to expand on the key points etc.).

Module ID

Modules are identified using a GUID. This ID allows the GoBus to connect to a module by scanning the bus for the specified ID. It also allows the Netduino Go to verify that when connecting to a module on a specific socket that the module is of the correct type. So the first thing we will need to do is obtain a new GUID. There are various ways in which we can do this and the simplest way to do this is to use the Create GUID menu option in Visual Studio. You can find this in the Tools menu.

Once you have your GUID you need to break this down into an array of bytes. You can then enter this in the both the Netduino code and the STM8S code. You will find the appropriate line in the file BasicModule.cs. The code looks something like this:

REMEMBER: It is critical that you generate your own GUID as each module type will need to have distinct ID.

Scanning down the file a little way you will find the two constructors for the class. One takes a socket and attempts to bind to the specified module on the requested socket. The other will attach to the first available module on the GoBus.

Initialise

This method is key to allowing the Netduino Go to connect to the module. The method binds to the module (assuming the IDs match) and retrieves a list of resources which the driver can use to communicate with the module. In this case, the SPI information and the pin used as an interrupt port. The remainder of the method configures the module driver to use these resources.

One key point to note is the use of the AutoResetEvent object. This is used to allow the interrupt handler to communicate the fact that an event has occurred to the methods we will write. This can be done in a manner which is non-blocking.

AddFive Method

This is the first of our methods implementing the functionality which our module will provide. In our case, this method actually implements the simple arithmetic we will be asking the module to perform. We will be sending a byte to the module, the module will add five to the number passed and then make this available to the Netduino Go. The code looks like this:

public byte AddFive(byte value)
{
	int retriesLeft = 10;
	bool responseReceived = false;

	_writeFrameBuffer[0] = GO_BUS10_COMMAND_RESPONSE;
	_writeFrameBuffer[1] = CMD_ADD_FIVE;
	_writeFrameBuffer[2] = value;
	WriteDataToModule();
	while (!responseReceived && (retriesLeft > 0))
	{
		//
		//  We have written the data to the module so wait for a maximum 
		//  of 5 milliseconds to see if the module responds with some 
		//  data for us.
		//
		responseReceived = _irqPortInterruptEvent.WaitOne(5, false);
		if ((responseReceived) && (_readFrameBuffer[1] == GO_BUS10_COMMAND_RESPONSE))
		{
			//
			//  Module has responded so extract the result.  Note we should really
			//  verify the checksum at this point.
			//
			_writeFrameBuffer[0] = GO_BUS10_COMMAND_RESPONSE;
			_writeFrameBuffer[1] = CMD_GET_RESULT;
			WriteDataToModule();
			return(_readFrameBuffer[2]);
		}
		else
		{
			//
			//  No response within the 5ms so lets make another attempt.
			//
			retriesLeft--;
			if (retriesLeft > 0)
			{
				WriteDataToModule();
			}
		}
	}
	throw new Exception("AddFive cannot communicate with the Basic GO! module");
}

The first thing this the method does is to set up the _writeFrameBuffer with the header, the command number and the data we will be sending. The data is then written to the module using SPI.

Next we will wait a while for the module to indicate via the GPIO pin that it has processed the data and the result is ready. As we shall see later, the module has already put the result in the transmission buffer ready for retrieval. This will have been performed before the interrupt was generated. The following line performs the non-blocking check to see if the interrupt has been generated:

responseReceived = _irqPortInterruptEvent.WaitOne(5, false);

responseReceived will be true if the interrupt has been generated and the C# module code has received the event.

The final task is to retrieve the result from the module by sending a retrieve command. This is performed by the following code:

_writeFrameBuffer[0] = GO_BUS10_COMMAND_RESPONSE;
_writeFrameBuffer[1] = CMD_GET_RESULT;
WriteDataToModule();
return(_readFrameBuffer[2]);

STM8S Module

Much of the code required here has already been covered in the previous post, STM8S SPI Slave (Part 2). The protocol uses a small buffer to allow messages to be transferred between the STM8S and the Netduino Go. In order to make this work as a Netduino Go module we need to overlay the GoBus protocol onto the message buffers and provide a mechanism for interpreting these messages. The mechanism we adopted is as follows:

• All messages will be restricted to 18 bytes (one byte header, 16 bytes payload, one byte CRC)
• The request header (from the Netduino to the module) will be 0x80 allowing a 16 byte payload
• The response header (from the module to the Netduino) will be 0x2a followed by 0x80. This restricts the return payload to 15 bytes.
• The final byte will be a CRC calculated on the header and the payload

The way in which the protocol has been implemented here also places a restriction upon on the application. Firstly, the module must receive a request as a full payload. Only then can the module respond. This is where the GPIO interrupt discussed earlier comes into play.

The final part of the problem is to work out how to dispatch the messages received by the module. To do this we will use a function table.

For the remainder of this article we will restrict ourselves to looking at the new functionality we will be adding on top of the previous post in order to allow the creation of a module.

Function Table

A function table in C is a simple list of function pointers. We will add to this by allowing a variable function identifier to be used to associate a byte ID with a particular method within the module. The following code allows the table to be setup:

//
//  Function table structure.
//
typedef struct
{
    unsigned char command;          //  Command number.
    void (*functionPointer)();      //  Pointer to the function to be executed.
} FunctionTableEntry;
//
//  Forward function declarations for the function table.
//
void AddFive();
void GetValue();
//
//  Table of pointers to functions which implement the specified commands.
//
FunctionTableEntry _functionTable[] = { { 0x01, AddFive }, { 0x02, GetValue } };
//
//  Number of functions in the function table.
//
const int _numberOfFunctions = sizeof(_functionTable) / sizeof(FunctionTableEntry);

Here we define a function table entry which has a byte ID and a pointer to a function (taking a void parameter list) associated with the ID. We then declare an array of these objects and associate functions with the IDs.

The final line of code simply determines the number of entries in the function table.

Using the above table we can work out which function to call using the following code:

if (_numberOfFunctions > 0)
{
	for (int index = 0; index < _numberOfFunctions; index++)
	{
		if (_functionTable[index].command == _rxBuffer[1])
		{
			(*(_functionTable[index].functionPointer))();
			break;
		}
	}
}

The function table method presented here allows the functionality of the module to be expanded with relative ease. In order to add a new piece of functionality you simply need to do the following:

• Create a new method in the STM8S code to implement the new functionality
• Determine the ID to be used for the functionality and add a new entry to the function table
• Create a method in the Netduino Go driver to call the method and retrieve any results as necessary

By performing these three simple steps you can add one or more functions with ease. The communication protocol will continue to work as is with no modification. The only exception to this rule will be cases where more than one payload of data needs to be transferred in order to achieve a specified piece of functionality (say a network driver etc.).

Buffers and GUIDs

We will need to make a slight modification to the Rx buffer in order to account for the checksum byte. We will also need to add somewhere to store the GUID which acts as the identifier for this module. This results in the following small change to the global variable code:

//
//  Application global variables.
//
unsigned char _rxBuffer[GO_BUFFER_SIZE + 1];    // Buffer holding the received data plus a CRC.
unsigned char _txBuffer[GO_BUFFER_SIZE];        // Buffer holding the data to send.
unsigned char *_rx;                             // Place to put the next byte received.
unsigned char *_tx;                             // Next byte to send.
int _rxCount;                                   // Number of characters received.
int _txCount;                                   // Number of characters sent.
volatile int _status;                           // Application status code.
//
//  GUID which identifies this module.
//
unsigned char _moduleID[] = { 0x80, 0x39, 0xe8, 0x2b, 0x55, 0x58, 0xeb, 0x48,
                              0xab, 0x9e, 0x48, 0xd3, 0xfd, 0xae, 0x8c, 0xee };

GoBus Interrupt

The discussion of the code on the Netduino Go driver (on the main board) mentioned the fact that the module can raise an interrupt to signal the fact that an operation has completed and that data is ready for retrieval. In order to do this we raise an interrupt on one of the pins when we have processed the data. This code is trivial:

//
//  Raise an interrupt to the GO! main board to indicate that there is some data
//  ready for collection.  The IRQ on the GO! board is configured as follows:
//
//  _irqPort = new InterruptPort((Cpu.Pin) socketGpioPin, false, Port.ResistorMode.PullUp,
//                               Port.InterruptMode.InterruptEdgeLow);
//
void NotifyGOBoard()
{
    PIN_GOBUS_INTERRUPT = 0;
    __no_operation();
    PIN_GOBUS_INTERRUPT = 1;
}

This method is simple and really just toggles which is connected to GPIO pin on the Netduino Go socket.

Adding Functionality to the Module

In our simple case we need to add two pieces of functionality, the ability to add five to a number and then to allow the caller to retrieve the result. This results in the following two methods:

//
//  GO! function 1 - add 5 to byte 2 in the Rx buffer and put the answer into the
//  Tx buffer.
//
void AddFive()
{
    _txBuffer[1] = _rxBuffer[2] + 5;
    NotifyGOBoard();
}

//--------------------------------------------------------------------------------
//
//  GO! Function 2 - return the Tx buffer back to the GO! board.
//
void GetValue()
{
    NotifyGOBoard();
}

SPI Go Frame

The implementation of the SPI processing here is interrupt driven. As such we will need to allow a method of synchronising the payloads we receive. This application will do this using the rising edge of the chip select signal which is generated by the Netduino Go main board. This allows us for cater for the many scenarios (synchronisation, underflow and overflow).

In the case of underflow and synchronisation, the chip select signal will rise before we have enough data. In this case we have either a corrupt packet or we have started to recei8ve data part way through the packet. In this case we cannot sensibly process the data so we should throw away the packet and wait for the next one.

An overflow situation can occur when the Netduino Go sends more than 18 bytes in one packet of data. In this case we should detect this and prevent the buffers from overflowing.

In order to allow for these cases we reset the Go frame pointers when the chip select signal changes from low to high:

//
//  This method resets SPI ready for the next transmission/reception of data
//  on the GO! bus.
//
//  Do not call this method whilst SPI is enabled as it will have no effect.
//
void ResetGoFrame()
{
    if (!SPI_CR1_SPE)
    {
        (void) SPI_DR;                          //  Reset any error conditions.
        (void) SPI_SR;
        SPI_DR = GO_FRAME_PREFIX;               //  First byte of the response.
        _txBuffer[0] = _moduleID[0];            //  Second byte in the response.
        //
        //  Now reset the buffer pointers and counters ready for data transfer.
        //
        _rx = _rxBuffer;
        _tx = _txBuffer;
        _rxCount = 0;
        _txCount = 0;
        //
        //  Note the documentation states this should be SPI_CR2_CRCEN
        //  but the header files have SPI_CR_CECEN defined.
        //
        SPI_CR2_CECEN = 0;                      //  Reset the CRC calculation.
        SPI_CR2_CRCNEXT = 0;
        SPI_CR2_CECEN = 1;
        SPI_SR_CRCERR = 0;
    }
}

As we shall see later, the end of the SPI transmission with result in one of the following cases:

• Too little data received correctly. The rising chip select line will reset the buffer pointers and the data will be discarded.
• The correct amount of data received. In this case the buffer will be processed correctly.
• Too much data is received. The excess data will be discarded to prevent a buffer overflow.

The ResetGoFrame method is key in ensuring that the buffers are reset at the end of the SPI transmission indicated by the rising chip select line.

SPI Tx/Rx Interrupt Handler

This method is responsible for ensuring that the data is transmitted and received correctly. It works in much the same way as the previous buffered SPI example. The main difference between this module and the previous example is what happens when the first byte of the data received is equal to 0xfe. In this case the Tx buffer pointer is moved to point to the module ID. This ensures that the Netduino Go receives the correct response to the enumeration request.

Connecting the Boards

The application code contains a number of #if statements to take into account the differing pin layouts of the microcontrollers used. The following have been tested so far:

• STM8S103F3 TSSOP20 on a breadboard
• STM8S Discovery

The Protomodule has also been wired up for one particular module but at the time of writing the definitions have not been added to the sources.

In order to connect the Netduino Go main board to a module in development you will probably need to purchase some form of breakout such as the Komodex breakout board (Straight connectors or 90-Degree connectors).

Connecting the two boards should be a simple case of ensuring that the SPI pins are connected MOSI to MOSI, MISO to MISO, CS to CS and Clock to Clock. In the case of the Discovery board I used PB0 for the CS line and for the STM8S103 setup I used the standard pin PA3.

Running the Code

Running the code should be a simple case of loading the STM8S code into the IAR development environment first and the deploying the code to the chip. Hot F5 to run the code.

Next, load the visual studio code and deploy this to the Netduino Go main board. Hit F5 to run the code.

The C# code running in Visual Studio should start to print some diagnostic information to the debug window. You should see a series of statements of the form Adding 5 to 6 to give 11. The 6 is the parameter which has been sent to the module for processing and the 11 is the result.

Observations

I have seen differing behaviours to the way in which the debugger in IAR works with the code in the module. Occasionally the debugger will actually prevent the module from enumerating. This will result in an exception in Visual Studio. To date I have only seen this behaviour with the STM8S103 setup. The STM8S Discovery board seems to work correctly. If you have problems with this then the only suggestion is to detach IAR from the board and rely upon diagnostic information being dumped to a logic analyser. You will note that the test application which runs on the Netduino Go has the instantiation of the module wrapped in a while loop and a try block. This allows the test code to make several attempts at creating a new module instance. This should not be necessary in the final production code as this has not yet failed in a none debug environment.

This code has been tested with the simple module example here and also with a temperature and humidity sensor. The application enumerated OK and has been soak tested in two environments over a period of hours. The code seems to be stable and works well with the Netduino Go.

I originally tried to be ambitious with the interrupt service routine dealing with the chip select line. This gave me code which was simpler but lead to a timing issue. As it stands at the moment, dropping the chip select line from high to low starts the SPI processing. The time between this happening and the first clock transition is only 3.25us as measured on my logic analyser. This means that all of the preparation must be completed in 3.25us.

If we look at the diagram below you can see the timings at the start of the SPI communication:



SPI Timing Diagram

The two markers 1 & 2 indicate the time we have between the start of the comms indicated by CS falling to the first clock pulse. The Status Code trace is a debugging signal generated by the application. The rising edge indicates when the first line of the interrupt service routine for the CS line starts and the falling edge indicates the point where we have completed enough processing to allow SPI to be enabled.

Conclusion

This post shows how we to create a Netduino Go module using a standard communication protocol. Additional module functionality can simply be added by adding to the function table.

As noted at the start, this article is the combination of information provided by Netduino community members along with the module code which can be found in the Wiki.

As usual, the source code for this application is available for download (STM8S Go Module and Netduino Go – Basic Module Driver).

Source Code Compatibility

System	Compatible?
STM8S103F3 (Breadboard)
Variable Lab Protomodule
STM8S Discovery