RSS

Posts Tagged ‘The Way of the Register’

Window Watchdog

Saturday, July 5th, 2014

Window watchdogs provide a mechanism for detecting software failures in two ways, firstly an early reset of the watchdog and secondly a failure to reset the watchdog in time. In this post we investigate how the window watchdog can be use and illustrate with some examples.

Hardware

Window Watchdog Control Register – WWDG_CR

This register has two components, the timer counter and the enable bit (WWDG_CR_WDGA – see below). The microcontroller will be reset when one of two possible conditions:

  • The counter switches from 0x40 to 0x3f (i.e. bit 6 in the counter changes from 1 to 0)
  • The counter is reset when the counter value is greater than the watchdog window register

Writing 0 to bit 6 will cause the microcontroller to be reset immediately.

Assuming that WWDG_WR contains the default reset value then the time out period (in milliseconds) is defined as follows:

tWWDG = tCPU * 12288 * (WWDG_CR & 0x3f)

where tCPU = 1 / fmaster

On the STM8S running at 16MHz a value of 0x40 represents one count which is equal to 0.768ms. So at 16MHz the time out period is:

tWWDG = 0.768 * (WWDG_CR & 0x3f)

Window Watchdog Enable Register – WWDG_CR_WDGA

Switch the Window Watchdog on (set to 1) or off (set to 0).

Window Watchdog Window Register – WWDG_WR

This register defines a time period where the watchdog counter should not be reset. If the counter (WWDG_CR) is reset when the counter value is greater than the value in this register the microcontroller will be reset. This can be illustrated as follows:

Watchdog Sequence

Watchdog Sequence

We can calculate the value of tWindowStart and ttimeout as follows (assuming a 16MHz clock):

tWindowStart = 0.768 * ((WWDG_CRinitial & 0x3f) – WWDG_WR)

and

ttimeout = 0.768 * (WWDG_CR & 0x3f)

where WWDG_CRinitial is the initial value in the WWDG_CR register.

The default reset value for this register is 0x7f which means that the counter can be reset at any time. In this case, a reset will only be generated if the counter drops below 0x40.

One important point to note is that when the window register is used the value written to the counter (WWDG_CR) must be between 0xc0 and 0x7f. This causes the counter to be reset and the counter value to be reset simultaneously.

Software

The function of the Window Watchdog will be illustrated using the following three examples:

  • WWDG_CR not reset
  • WWDG_CR reset outside the reset window
  • WWDG_CR reset inside the reset window

The first thing we need to do is add some code which will be used in all of the examples.

Common Code

Firstly, lets add the code which will be common to all of the examples:

//
//  This program demonstrates how to use the Window Watchdog on the STM8S
//  microcontroller.
//
//  This software is provided under the CC BY-SA 3.0 licence.  A
//  copy of this licence can be found at:
//
//  http://creativecommons.org/licenses/by-sa/3.0/legalcode
//
#include <iostm8S105c6.h>
#include <intrinsics.h>

//--------------------------------------------------------------------------------
//
//  Setup the system clock to run at 16MHz using the internal oscillator.
//
void InitialiseSystemClock()
{
    CLK_ICKR = 0;                       //  Reset the Internal Clock Register.
    CLK_ICKR_HSIEN = 1;                 //  Enable the HSI.
    CLK_ECKR = 0;                       //  Disable the external clock.
    while (CLK_ICKR_HSIRDY == 0);       //  Wait for the HSI to be ready for use.
    CLK_CKDIVR = 0;                     //  Ensure the clocks are running at full speed.
    CLK_PCKENR1 = 0xff;                 //  Enable all peripheral clocks.
    CLK_PCKENR2 = 0xff;                 //  Ditto.
    CLK_CCOR = 0;                       //  Turn off CCO.
    CLK_HSITRIMR = 0;                   //  Turn off any HSIU trimming.
    CLK_SWIMCCR = 0;                    //  Set SWIM to run at clock / 2.
    CLK_SWR = 0xe1;                     //  Use HSI as the clock source.
    CLK_SWCR = 0;                       //  Reset the clock switch control register.
    CLK_SWCR_SWEN = 1;                  //  Enable switching.
    while (CLK_SWCR_SWBSY != 0);        //  Pause while the clock switch is busy.
}

//--------------------------------------------------------------------------------
//
//  Initialise the ports.
//
//  Configure all of Port D for output.
//
void InitialisePorts()
{
    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.
}

This code has been used many times in The Way of the Register series of posts. It simply sets the system clock to the high speed internal clock and configures Port D for output.

Example 1 – Continuous Reset

This example sets the Windows Watchdog running and then waits for the watchdog to trigger the system reset. We indicate that the application is running by generating a pulse on Port D, pin 2.

//--------------------------------------------------------------------------------
//
//  Initialise the Windows Watchdog.
//
void InitialiseWWDG()
{
    PD_ODR_ODR2 = 1;
    __no_operation();
    __no_operation();
    __no_operation();
    __no_operation();
    PD_ODR_ODR2 = 0;
    WWDG_CR = 0xc0;
}

The __no_operation() instruction in the above code allow the pulse to stabilise on the pin.

The WWDG_CR is set to 0xc0 to both set the value in the counter and enable the watchdog at the same time. This sets bit 6 in the counter to 11 and the remaining bits to 0 (i.e. the counter is set to 0x40). The effect of this is that the first down count event will cause bit 6 to be cleared and the counter to be set to 0x3f. This will trigger the reset event.

The main program simply sets everything up and then “pauses” by simply waiting for an interrupt:

//--------------------------------------------------------------------------------
//
//  Main program loop.
//
int main()
{
    //
    //  Initialise the system.
    //
    __disable_interrupt();
    InitialiseSystemClock();
    InitialisePorts();
    InitialiseWWDG();
    __enable_interrupt();
    //
    //  Main program loop.
    //
    while (1)
    {
        __wait_for_interrupt();
    }
}

If we run this application and connect PD2 and NRST to the oscilloscope we see the following trace:

Initial continuous reset

Initial continuous reset

The yellow trace shows the reset line being pulled low and gradually returning to high. The drop shows where the watchdog has caused the reset pin to be pulled low and the microcontroller to be reset. The blue trace shows the pulse on PD2. If we measure the time difference between the pulse on PD2 and the time that the reset pin is pulled low we find that this is 770uS. This is very close to the time for one count, 768uS.

To verify this we can change the value in the counter to say 0x48. In this case we should see the watchdog running for 9 counts and the system running for 6.912mS. Changing WWDG_CR = 0xc0 to WWDG_CR = 0xc8 gives the following output on the oscilloscope:

Continuous reset

Continuous reset

Measuring the time difference we get a value of 6.9mS.

Example 2 – Reset Outside Watchdog Window

Using the above code as a starting point we will look at the effects of the watch dog window register (WWDG_WR). This defines when the application is allowed to change the value in the counter. The first task is to change the initial value in the control register to 0xc1 and verify that we get a rest every 1.54ms (2 x timer period). So change the InitialiseWWDG method to the following:

void InitialiseWWDG()
{
    PD_ODR_ODR2 = 1;
    __no_operation();
    __no_operation();
    __no_operation();
    __no_operation();
    PD_ODR_ODR2 = 0;
    WWDG_CR = 0xc1;
}

Running this application on the STM8S Discovery board results in the following traces:

Reset Outside window

Reset Outside window

Now we have two counts (1.54mS) in order to change the value in the control register. First task is to modify the InitialiseWWDG method to define the window. We will define this to be 0x40:

void InitialiseWWDG()
{
    PD_ODR_ODR2 = 1;
    __no_operation();
    __no_operation();
    __no_operation();
    __no_operation();
    PD_ODR_ODR2 = 0;
    WWDG_CR = 0xc1;
    WWDG_WR = 0x40;
}

This means that for the first 768uS the control register should not be changed. If the register is changed during this period a reset will be triggered. To demonstrate this we will change the value in the control register immediately after the microcontroller has been initialised:

int main()
{
    //
    //  Initialise the system.
    //
    __disable_interrupt();
    InitialiseSystemClock();
    InitialisePorts();
    InitialiseWWDG();
    __enable_interrupt();
    //
    //  Main program loop.
    //
    while (1)
    {
        WWDG_CR = 0xc1;             //  Trigger a reset.
        __wait_for_interrupt();
    }
}

Deploying this application to the microcontroller results in the following trace on the oscilloscope:

Watchdog immediate reset

Watchdog immediate reset

As you can see, the system is reset almost immediately (there is virtually no time between the pulse on PD2 and the reset line being pulled low).

Example 3 – Reset Within the Watchdog Window

Starting with the common code we initialise the Window Watchdog with the following method:

//--------------------------------------------------------------------------------
//
//  Initialise the Windows Watchdog.
//
void InitialiseWWDG()
{
    WWDG_CR = 0x5b;         //  Approx 70ms total window.
    WWDG_WR = 0x4c;         //  Approx 11.52ms window where cannot reset
    WWDG_CR_WDGA = 1;       //  Enable the watchdog.
}

This code defines a period of 11.52ms where we cannot reset the window watchdog counter followed by a period of 9.216ms during which the watchdog counter must be reset in order to prevent the microcontroller from being reset.

A simple main application loop would look something like this:

//--------------------------------------------------------------------------------
//
//  Main program loop.
//
int main()
{
    //
    //  Initialise the system.
    //
    __disable_interrupt();
    InitialiseSystemClock();
    InitialisePorts();
    PD_ODR_ODR4 = 1;
    __no_operation();
    PD_ODR_ODR4 = 0;
    InitialiseWWDG();
    __enable_interrupt();
    //
    //  Main program loop.
    //
    while (1)
    {
        unsigned char counter = (unsigned char) WWDG_CR;
        if ((counter & 0x7f) < WWDG_WR)
        {
            WWDG_CR = 0xdb;     //  Reset the Window Watchdog counter.
            PD_ODR_ODR2 = !PD_ODR_ODR2;
        }
        //
        //  Do something here.
        //
    }
}

The initial pulse on PD4 indicates that the application has started. We can use this to detect the reset of the microcontroller. In this trivial application the main program loop simply checks to see if the current value of the counter is less than the value in WWDG_WR. If the counter is less than WWDG_WR then the system write a new value into the counter. The value written is 0x5b anded with 0x80, this brings the reset value into the value range (0xc0 – 0xff).

This application also pulses PD2 to indicate that the watchdog counter has been reset.

Deploying this application and hooking up the Saleae logic analyser gives the following trace:

Window watchdog initial trace

Window watchdog initial trace

As you can see, there is an initial pulse showing that the board is reset (top trace) and then a series of pulses showing that the counter is being reset (lower trace). Each up/down transition represents a watchdog counter reset.

This is a relatively trivial example so let’s spice this up and add in a timer.

To the code above add the following code:

//--------------------------------------------------------------------------------
//
//  Setup Timer 2 to generate a 12.5ms interrupt.
//
void SetupTimer2()
{
    TIM2_PSCR = 0x02;       //  Prescaler = 4.
    TIM2_ARRH = 0xc3;       //  High byte of 50,000.
    TIM2_ARRL = 0x50;       //  Low byte of 50,000.
    TIM2_IER_UIE = 1;       //  Enable the update interrupts.
    TIM2_CR1_CEN = 1;       //  Finally enable the timer.
}

This method will set up timer 2 to generate an interrupt every 12.5ms.

Adding the following will catch the interrupt:

//--------------------------------------------------------------------------------
//
//  Timer 2 Overflow handler.
//
#pragma vector = TIM2_OVR_UIF_vector
__interrupt void TIM2_UPD_OVF_IRQHandler(void)
{
    if (_firstTime)
    {
        InitialiseWWDG();
        _firstTime = 0;
    }
    else
    {
        unsigned char counter = (unsigned char) WWDG_CR;
        unsigned char window = WWDG_WR;
        BitBangByte(counter & 0x7f);
        BitBangByte(window);
        WWDG_CR = 0xdb;     //  Reset the Window Watchdog counter.
        counter = (unsigned char) WWDG_CR;
        BitBangByte(counter);
    }
    PD_ODR_ODR2 = !PD_ODR_ODR2;
    TIM2_SR1_UIF = 0;       //  Reset the interrupt otherwise it will fire again straight away.
}

The interrupt will, on first invocation, initialise the window watchdog. Subsequent invocations will output the values of the registers and reset the window watchdog.

We need some code to bit bang the register values:

#define SR_CLOCK            PD_ODR_ODR5
#define SR_DATA             PD_ODR_ODR3

//
//  BitBang the data through the GPIO ports.
//
void BitBangByte(unsigned char b)
{
    //
    //  Initialise the clock and data lines into known states.
    //
    SR_DATA = 0;                    //  Set the data line low.
    SR_CLOCK = 0;                   //  Set the clock low.
    //
    //  Output the data.
    //
    for (int index = 7; index >= 0; index--)
    {
        SR_DATA = ((b >> index) & 0x01);
        SR_CLOCK = 1;               //  Send a clock pulse.
        __no_operation();
        SR_CLOCK = 0;
    }
    //
    //  Set the clock and data lines into a known state.
    //
    SR_CLOCK = 0;                   //  Set the clock low.
    SR_DATA = 0;
}

The main program loop needs to be modified to set up the timer and registers etc. So replace the main program loop with the following:

//--------------------------------------------------------------------------------
//
//  Main program loop.
//
int main()
{
    //
    //  Initialise the system.
    //
    __disable_interrupt();
    InitialiseSystemClock();
    InitialisePorts();
    PD_ODR_ODR4 = 1;
    __no_operation();
    PD_ODR_ODR4 = 0;
    SetupTimer2();
    InitialiseWWDG();
    __enable_interrupt();
    //
    //  Main program loop.
    //
    while (1)
    {
        __wait_for_interrupt();
    }
}

Deploying and running this application gives the following output on the Saleae logic analyser:

Window watchdog full trace

Window watchdog full trace

Zooming in produces the following

Window watchdog zoomed in

Window watchdog zoomed in

Starting with the top trace and descending we can see the following values:

  • Reset pulse
  • Timer 2 interrupt triggers (up/down transitions)
  • Data (register values)
  • Clock signal

The decoded register values can be seen above the data trace. The first value is the current value of the counter. The second value is the value in the window watchdog register and the final value is the new value in the counter register.

Conclusion

The Window Watchdog provides a mechanism for the developer to detect software faults similar to the Independent Watchdog but further constrains the developer by defining a window where a counter reset by the application is not allowed.

STM8S Beep Function

Tuesday, July 1st, 2014

The beep function uses the 128 KHz LSI to generate a beep signal on the beep pin of the STM8S. This post demonstrates how to use this function.

Hardware

The signal is output on the beep pin. On the STM8S discovery board this is an alternative function on PD4 (port D, pin 4).

Setting the Alternative Function

The alternative functions are assigned to a pin by reprogramming the option bytes. This can be performed using the ST Visual Programmer. Start this application and read the option bytes from the STM8S:

Reading the options bytes using ST Visual Developer

Reading the options bytes using ST Visual Developer

  1. Select the STM8S model. On the STM8S Discovery board this is STM8S105C6
  2. Select the OPTION BYTE tab
  3. Read the option bytes from the microcontroller
  4. Check the value of the AFR7 bit

AFR7 needs to be set to Port D4 Alternative Function = BEEP on the STM8S Discovery board. This may be different on your STM8S so check the documentation for your microcontroller. To set the alternative function to beep:

Writing new options bytes using ST Visual Developer

Writing new options bytes using ST Visual Developer

  1. Select Port D4 Alternative Function = BEEP from the list of values in the alternative functions
  2. Write the option bytes back to the microcontroller

The beep function should now be assigned to PD4.

Registers

The beep function is controlled by three registers:

  • BEEP_CSR_BEEPSEL
  • BEEP_CSR_BEEPDIV
  • BEEP_CSR_BEEPEN

Beep Selection – BEEP_CSR_BEEPSEL

These bits set the multiplier for the Beep Divider.

BEEP_CSR_BEEPSELFrequency (KHz)
0fLSI / (8 * BEEPDIV)
1fLSI / (4 * BEEPDIV)
2 or 3fLSI / (2 * BEEPDIV)

Beep Divider – BEEP_CSR_BEEPDIV

Value for the prescalar divider.

BEEPDIV = 2 + BEEP_CSR_BEEPDIV

The documentation states that this should not be left set to the reset value (0x1f) and the value should be in the range 0 – 0x1e.

Beep Enable – BEEP_CSR_BEEPEN

Enable the beep function by setting this to 1, disable by setting this to 0.

Software

We start by providing a method for resetting the system clock to use the HSI:

//
//  This program demonstrates how to use the beep function on the STM8S 
//  microcontroller.
//
//  This software is provided under the CC BY-SA 3.0 licence.  A
//  copy of this licence can be found at:
//
//  http://creativecommons.org/licenses/by-sa/3.0/legalcode
//
#include <iostm8S105c6.h>
#include <intrinsics.h>

//--------------------------------------------------------------------------------
//
//  Setup the system clock to run at 16MHz using the internal oscillator.
//
void InitialiseSystemClock()
{
    CLK_ICKR = 0;                       //  Reset the Internal Clock Register.
    CLK_ICKR_HSIEN = 1;                 //  Enable the HSI.
    CLK_ECKR = 0;                       //  Disable the external clock.
    while (CLK_ICKR_HSIRDY == 0);       //  Wait for the HSI to be ready for use.
    CLK_CKDIVR = 0;                     //  Ensure the clocks are running at full speed.
    CLK_PCKENR1 = 0xff;                 //  Enable all peripheral clocks.
    CLK_PCKENR2 = 0xff;                 //  Ditto.
    CLK_CCOR = 0;                       //  Turn off CCO.
    CLK_HSITRIMR = 0;                   //  Turn off any HSIU trimming.
    CLK_SWIMCCR = 0;                    //  Set SWIM to run at clock / 2.
    CLK_SWR = 0xe1;                     //  Use HSI as the clock source.
    CLK_SWCR = 0;                       //  Reset the clock switch control register.
    CLK_SWCR_SWEN = 1;                  //  Enable switching.
    while (CLK_SWCR_SWBSY != 0);        //  Pause while the clock switch is busy.
}

The next task is to configure the beep function:

//--------------------------------------------------------------------------------
//
//  Initialise the Beep function.
//
void InitialiseBeep()
{
    BEEP_CSR_BEEPEN = 0;    //  Turn off the beep.
    BEEP_CSR_BEEPSEL = 0;   //  Set beep to fls / (8 * BEEPDIV) KHz.
    BEEP_CSR_BEEPDIV = 0;   //  Set beep divider to 2.
    BEEP_CSR_BEEPEN = 1;    //  Re-enable the beep.
}

The final piece of code is the main program loop. This sets up the clock and the beep function:

//--------------------------------------------------------------------------------
//
//  Main program loop.
//
void main()
{
    //
    //  Initialise the system.
    //
    __disable_interrupt();
    InitialiseSystemClock();
    InitialiseBeep();
    __enable_interrupt();
    //
    //  Main program loop.
    //
    while (1)
    {
        __halt();
    }
}

Compiling this code and deploying to the STM8S results in the following trace on the oscilloscope:

Beep Oscilloscope Output

Beep Oscilloscope Output

As you can see, the output is not exactly 8KHz.

Conclusion

The documentation states that the beep function can generate 1KHz, 2KHz and 4KHz. By changing the values of the prescalar and the selection register it appears that you can also go as low as 500Hz and as high as 32KHz.

STM8S Independent Watchdog

Saturday, June 21st, 2014

The Independent Watchdog (IWDG) allows the developer to detect software failures and reset the STM8S microcontroller restarting the application. This post demonstrates how this feature works and how the developer can change the time window for the watchdog.

Watchdogs offer the application developer a simple to use method of determining if an application has entered a state which means that it is locked or taking too long to perform an operation.

The first task is to define what we mean by too long. This will vary from one application to another but the key point is that this should be longer than the longest operation the application will perform plus a margin. Once we have this time period defined we know that the application must reset the IWDG before the time period has elapsed.

Hardware

Independent Watchdog Key Register – IWDG_KR

The Key Register controls the operation of the IWDG. The allowed values are as follows:

ValueDescription
0x55Enable writing to the IWDG_PR and IWDG_RLR registers. These registers are write protected by default.
0xAAReset the IWDG counter to the reload value. This value must be written to the key register periodically in order to prevent the watchdog from resetting the microcontroller.
0xCCEnable and start the IWDG.
0x00Disable writing to the IWDG_PR and IWDG_RLR registers.

The final value in the table is not present in revision 9 of RM0016 – Reference Manual but does appear in the header files for the STD Peripheral Library.

In researching this post a key point in the documentation was missed, namely IWDG_PR and IWDG_RLR can only be written when the IWDG has actually been enabled. This means that the IWDG needs to be running before the prescaler and reload registers can be loaded with the values required by the application. If the IWDG is not running then the system will resort to the default reset values for these registers. This gives a watchdog window of 16ms. It also means that the application has 16ms to set the desired time window through the IWDG_PR and IWDG_RLR registers before the microcontroller is reset.

Independent Watchdog Prescaler – IWDG_PR and Independent Watchdog Reload Register – IWDG_RLR

These two registers define the watchdog window and can. The default values are IWDG_PR = 0 and IWDG_RLR = 0xff. This gives a watchdog window of approximately 16ms. To change the size of the watchdog window use the table below to determine the values which are appropriate for your application:

Prescaler DividerPrescaler Value (IWDG_PR)Period when RL = 0Period when RL = 0xff
4062.5 us15.90 ms
81125 us31.90 ms
162250 us63.70 ms
323500 us127 ms
6441.00 ms255 ms
12852.00 ms510 ms
25664.00 ms1.02 s

The programming reference for the STM8S gives the following formula for determining the exact reset period:

T = 2 x TLSI x P x R

where:

TTimeout period
TLSI1 / fLSI
P2(IWDG_PR + 2)
RIWDG_RLR + 1

Additionally, the time between the last reset of the key register (i.e. writing 0xAA to IWDG_KR) is T + 6 x TLSI.

Software

So lets look at how we can implement this:

//
//  This program demonstrates how to use the Independent Watchdog timer
//  on the STM8S microcontroller in order to detect software failures and
//  reset the microcontroller.
//
//  This software is provided under the CC BY-SA 3.0 licence.  A
//  copy of this licence can be found at:
//
//  http://creativecommons.org/licenses/by-sa/3.0/legalcode
//
#include <iostm8S105c6.h>
#include <intrinsics.h>

//--------------------------------------------------------------------------------
//
//  Setup the system clock to run at 16MHz using the internal oscillator.
//
void InitialiseSystemClock()
{
    CLK_ICKR = 0;                       //  Reset the Internal Clock Register.
    CLK_ICKR_HSIEN = 1;                 //  Enable the HSI.
    CLK_ECKR = 0;                       //  Disable the external clock.
    while (CLK_ICKR_HSIRDY == 0);       //  Wait for the HSI to be ready for use.
    CLK_CKDIVR = 0;                     //  Ensure the clocks are running at full speed.
    CLK_PCKENR1 = 0xff;                 //  Enable all peripheral clocks.
    CLK_PCKENR2 = 0xff;                 //  Ditto.
    CLK_CCOR = 0;                       //  Turn off CCO.
    CLK_HSITRIMR = 0;                   //  Turn off any HSIU trimming.
    CLK_SWIMCCR = 0;                    //  Set SWIM to run at clock / 2.
    CLK_SWR = 0xe1;                     //  Use HSI as the clock source.
    CLK_SWCR = 0;                       //  Reset the clock switch control register.
    CLK_SWCR_SWEN = 1;                  //  Enable switching.
    while (CLK_SWCR_SWBSY != 0);        //  Pause while the clock switch is busy.
}

//--------------------------------------------------------------------------------
//
//  Initialise the ports.
//
//  Configure all of Port D for output.
//
void InitialisePorts()
{
    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.
}

The code above should be pretty familiar to anyone who has been following The Way of the Register series of posts. This sets up the system clock to run at 16MHz and sets port D as an output port.

//--------------------------------------------------------------------------------
//
//  Initialise the Independent Watchdog (IWDG)
//
void InitialiseIWDG()
{
    IWDG_KR = 0xcc;         //  Start the independent watchdog.
    IWDG_KR = 0x55;         //  Allow the IWDG registers to be programmed.
    IWDG_PR = 0x02;         //  Prescaler is 2 => each count is 250uS
    IWDG_RLR = 0x04;        //  Reload counter.
    IWDG_KR = 0xaa;         //  Reset the counter.
}

We follow this up by setting up the IWDG. The prescaler and counter values should give a 1ms window.

//--------------------------------------------------------------------------------
//
//  Main program loop.
//
int main()
{
    //
    //  Initialise the system.
    //
    __disable_interrupt();
    InitialiseSystemClock();
    InitialisePorts();
    InitialiseIWDG();
    __enable_interrupt();
    __halt();
}

The main program configures the system and then halts the microcontroller. Without the watchdog this would the end of the application. With the watchdog we should see the microcontroller continuously resetting. This can be verified by connecting an oscilloscope to Port D. If we do this we see the output on the port rise as the microcontroller is reset and the InitialisePorts method is called.

Now replace the __halt(); statement with the following code:

while (1)
{
    IWDG_KR = 0xaa;
}

This code continuously writes the I am alive message to the IWDG key register. Doing this forces the IWDG to reset the counters with the reload values and start again. Running this application we see a flat line following the initial reset of the microcontroller. The flat line indicates that the microcontroller is not being reset.

Conclusion

The Independent Watchdog provides a simple method for detecting software failures merely writing a reset value into the key register.

Earlier the point was made that it appears that the IWDG must be enabled (and hence running) before the prescaler and reload registers can be modified. This point is critical as the microcontroller will resort to the reset values otherwise.

Although not demonstrated here it is possible for the application to determine if the application has been started through the application of power to the microcontroller or because of a reset by the IWDG. This can be determined by checking the value in RST_SR_IWDGF. This will be set to 1 if the IWDG has caused the microcontroller to be reset or 0 otherwise. This is left as an exercise for the reader.

Download

The source code for this post is available for download.

Auto-Wakeup on the STM8S

Friday, June 20th, 2014

A few days ago I was asked for advice about pausing the STM8S for a long time period (in this case 30 seconds). I had to admit that I was not sure how to achieve this without using a timer and counting interrupts until the 30 time period had expired. A quick examination of the STM8S Programming Reference reveals that there is a simpler way of doing this. This post examines the Auto-Wakeup (AWU) feature of the STM8S and shows how this feature can be used to pause for a time period which can range from 15.625uS to 30.720s, assuming the clock source is accurate.

Auto-Wakeup (AWU) Feature

The AWU feature wakes the STM8S after a predefined time period following the microcontroller going into the active halt state. This feature can only be used when the microcontroller is halted and the accuracy is dependent upon the clock source.

The clock source is fed into a prescalar. The output from the prescalar is then used as a clock for a counter. The counter will cause an interrupt to be generated when the preset counter value has been reached.

It is also possible to determine the accuracy of the clock source by using the capture compare feature of TIM1 or TIM3 to measure the clock frequency.

Auto-Wakeup Registers

The function of the AWU is determined by the values in the AWU control registers.

Auto-Wakeup Enable – AWU_CSR1_AWUEN

Setting this bit to 1 enables the AWU function. Setting this to 0 disables the function.

Auto-Wakeup Asynchronous Prescalar Divider – AWU_APR_APR and Auto-Wakeup Timebase Selection Register – AWU_TBR_AWUTB

These two registers together control the duration of the AWU. The exact duration of the wakeup period is determined by the AWU_APR_APR and AWU_TBR_AWUTB values from the following table.

fLS = ffLS = 128 kHzAWU_TBR_AWUTBAPRDIV FormulaAWU_APR_APR Range
2/f – 64/f0.015625 ms – 0.5 ms0001APRDIV/fLS2 to 64
2×32/f – 2x2x32/f0.5 ms – 1.0 ms00102 x APRDIV/fLS32 to 64
2×64/f – 2x2x64/f1 ms – 2 ms001122 x APRDIV/fLS32 to 64
22×64/f – 22×128/f2 ms – 4ms010023 x APRDIV/fLS32 to 64
23×64/f – 23×128/f4 ms – 8 ms010124 x APRDIV/fLS32 to 64
24×64/f – 24×128/f8 ms – 16 ms011025 x APRDIV/fLS32 to 64
25×64/f – 25×128/f16 ms – 32 ms011126 x APRDIV/fLS32 to 64
26×64/f – 26×128/f32 ms – 64 ms100027 x APRDIV/fLS32 to 64
27×64/f – 27×128/f64 ms – 128 ms100128 x APRDIV/fLS32 to 64
28×64/f – 28×128/f128 ms – 256 ms101029 x APRDIV/fLS32 to 64
29×64/f – 29×128/f256 ms – 512 ms1011210 x APRDIV/fLS32 to 64
210×64/f – 210×128/f512 ms – 1.024 s1100211 x APRDIV/fLS32 to 64
211×64/f – 211×128/f1.024 s – 2.048 s1101212 x APRDIV/fLS32 to 64
211×130/f – 211×320/f2.080 s – 5.120 s11105 x 211 x APRDIV/fLS26 to 64
211×330/f – 212×960/f5.280 s – 30.720s111130 x 211 x APRDIV/fLS11 to 64

Where fLS = f is the formula which should be used when the inbuilt LSI is not being used.

It may not be possible to obtain an exact time period and the application may have to use the values which give the closest period.

When not in use, AWU_TBR_AWUB should be set to 0 in order to reduce power consumption.

Auto-Wakeup Flag – AWU_CSR1_AWUF

This flag is set when the AWU interrupt has been generated. The flag is cleared by reading the AWU control/status register (AWU_CSR1).

Auto-Wakeup Measurement Enable – AWU_CSR1_MSR

Setting this flag to 1 connects the output from the prescalar to one of the internal timers. This allows the application to accurately determine the clock frequency connected to the AWU prescalar. By measuring the clock frequency the application can adjust the values used for the prescalar divider and the timebase.

Software

Now we have the theory it is time to break out the STM8S Discovery board and the IAR compiler. The application starts pretty much the same as previous examples in this series, by setting the system clock and configuring a port for output:

//
//  This program demonstrates how to use the Auto-Wakeup feature of the STM8S
//  microcontroller.
//
//  This software is provided under the CC BY-SA 3.0 licence.  A
//  copy of this licence can be found at:
//
//  http://creativecommons.org/licenses/by-sa/3.0/legalcode
//
#include <iostm8S105c6.h>
#include <intrinsics.h>

//--------------------------------------------------------------------------------
//
//  Setup the system clock to run at 16MHz using the internal oscillator.
//
void InitialiseSystemClock()
{
    CLK_ICKR = 0;                       //  Reset the Internal Clock Register.
    CLK_ICKR_HSIEN = 1;                 //  Enable the HSI.
    CLK_ECKR = 0;                       //  Disable the external clock.
    while (CLK_ICKR_HSIRDY == 0);       //  Wait for the HSI to be ready for use.
    CLK_CKDIVR = 0;                     //  Ensure the clocks are running at full speed.
    CLK_PCKENR1 = 0xff;                 //  Enable all peripheral clocks.
    CLK_PCKENR2 = 0xff;                 //  Ditto.
    CLK_CCOR = 0;                       //  Turn off CCO.
    CLK_HSITRIMR = 0;                   //  Turn off any HSIU trimming.
    CLK_SWIMCCR = 0;                    //  Set SWIM to run at clock / 2.
    CLK_SWR = 0xe1;                     //  Use HSI as the clock source.
    CLK_SWCR = 0;                       //  Reset the clock switch control register.
    CLK_SWCR_SWEN = 1;                  //  Enable switching.
    while (CLK_SWCR_SWBSY != 0);        //  Pause while the clock switch is busy.
}

//--------------------------------------------------------------------------------
//
//  Initialise the ports.
//
//  Configure all of Port D for output.
//
void InitialisePorts()
{
    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.
}

The next step is to provide a method to initialise the AWU function:

//--------------------------------------------------------------------------------
//
//  Initialise the Auto Wake-up feature.
//
//
//
void InitialiseAWU()
{
    AWU_CSR1_AWUEN = 0;     // Disable the Auto-wakeup feature.
    AWU_APR_APR = 38;
    AWU_TBR_AWUTB = 1;
    AWU_CSR1_AWUEN = 1;     // Enable the Auto-wakeup feature.
}

Firstly, the AWU function is disabled. The prescalar is set followed by the timebase. The final step is to re-enable the AWU.

//--------------------------------------------------------------------------------
//
//  Auto Wakeup Interrupt Service Routine (ISR).
//
//  Pulse PD0 for a short time.  The NOP instructions generate a more stable
//  pulse on the oscilloscope.
//
#pragma vector = AWU_vector
__interrupt void AWU_IRQHandler(void)
{
    volatile unsigned char reg;

    PD_ODR = 1;
    asm("nop;");
    asm("nop;");
    PD_ODR = 0;
    reg = AWU_CSR1;     // Reading AWU_CSR1 register clears the interrupt flag.
}

This interrupt handler is triggered at the end of the AWU period. This handler simply pulses pin 0 on port D.

//--------------------------------------------------------------------------------
//
//  Main program loop.
//
int main(void)
{
    //
    //  Initialise the system.
    //
    __disable_interrupt();
    InitialiseSystemClock();
    InitialisePorts();
    InitialiseAWU();
    __enable_interrupt();
    //
    //  Main program loop.
    //
    while (1)
    {
        __halt();
    }
}

The AWU function is turned on when the microcontroller enters the active halt state. A halt instruction is generated by the __halt() method.

Running the above code on the STM8S Discovery board results in the following trace on the oscilloscope:

AWU 3208Hz Signal

AWU 3208Hz Signal

and:

AWU Expanded Pulse

AWU Expanded Pulse

Examining the table above and the values used for the precalar and timebase we should be seeing a pulse with a frequency of approximately 3,368Hz. The actual value measured on the oscilloscope is 3,208Hz. The measurement on the oscilloscope will alway be slightly out due to the time it takes for the ISR to be setup and called. An ISR on the STM8S takes 9 clock cycles to be established, this equates to about 560nS on a system running at 16MHz. The actual difference is 6.25mS. The remainder of the difference comes from the fact that the LSI has an accuracy of +/-12.5%. A quick calculation shows the the LSI was running at about 121KHz at the time this post was written.

Conclusion

AWU offers a simple way of triggering processing at predetermined time periods. The active halt state puts the microcontroller into a low power mode whilst the microcontroller is waiting for the time period to elapse.

It should also be noted that using the LSI results in a slightly variable time period.

Storing Data in EEPROM on the STM8S

Thursday, September 12th, 2013

During a recent project it became desirable to store a small amount of data in some non-volatile memory in order that the system state could be restored following loss of power. This article demonstrates how to achieve this by writing a small amount of data to the data EEPROM of the STM8S105Cr micro-controller on the STM8S Discovery board.

Memory Layout, Access and Protection

The Data EEPROM area of the STM8S series of micro-controllers varies depending upon the specific unit being used. For this article the specific micro-controller being used is the STM8S105C6 on the STM8S Discovery board. This micro-controller has 1KByte of EEPROM in the address range 0x4000 – 0x43ff.

By default the data area is write protected and cannot be modified by the main program. The write protection is removed by using a key to unlock the EEPROM data area. The flash program area is similarly protected but we will only consider the data EEPROM area. In order to write to the EEPROM area the application will need to write two security keys called Memory Access Security System (MASS) keys to the FLASH_DUKR register. These keys will unlock the EEPROM area and allow the application to write data to the EEPROM until the application turns write protection back on.

The MASS keys for the data EEPROM area are:

  • 0xae
  • 0x56
  • The algorithm for enabling write access to the EEPROM data area is as follows:

    • Check the DUL bit of FLASH_IASPR. If this bit is set then the data area is writeable and no further action is required.
    • Write the first MASS key (0xae) to the FLASH_DUKR register.
    • Write the second MASS key (0x56) to the FLASH_DUKR register.

    At the end of the process of successfully writing the MASS keys the DUL bit of the FLASH_IASPR register will be set. This bit will remain set until either the application changes the bit or the micro-controller is reset. Resetting the DUL bit programatically reinstates the write protection for the EEPROM memory.

    Read-while-write (RWW)

    This feature is not available on all of the STM8S family of processors and you should consult the data sheet for the unit being used if you are interested in using this feature. The RWW feature allows the program memory to be read whilst the EEPROM memory is being written to.

    Byte Programming

    Byte level programming is available for both the program memory and the EEPROM memory. To use this feature the application simply needs to unlock the EEPROM using the MASS keys and then write individual bytes into the EEPROM memory. To erase a byte simply write 0x00 into the memory location.

    Word and Page Programming

    The STM8S also allows word (4 bytes) and block programming. Both of these are faster than byte programming and block programming is faster than word programming. These features will not be discussed further here and are mentioned simply for awareness.

    Interrupts

    The system can be configured to generate an interrupt for the following event:

    • Successful write operation.
    • Successful erase operation.
    • Illegal operation (writing to protected pages).

    Interrupts are enabled by setting FLASH_CR1_IE to 1. When this bit is set, an interrupt will be generated when the FLASH_IASPR_EOP or FLASH_IASPR_WR_PG_DIS bits are set.

    Software

    The original aim of the software was to write a small amount of data to the data EEPROM of the STM8S and use the ST Visual Programmer to verify that the memory contents had changed. As the project progressed it became apparent that we would also need some code to verify the data.

    Writing the Data

    The application to write data to the EEPROM is relatively simple:

    //
    //  Write a series of bytes to the EEPROM of the STM8S105C6.
    //
    //  This software is provided under the CC BY-SA 3.0 licence.  A
    //  copy of this licence can be found at:
    //
    //  http://creativecommons.org/licenses/by-sa/3.0/legalcode
    //
    #if defined DISCOVERY
        #include <iostm8S105c6.h>
    #else
        #include <iostm8s103f3.h>
    #endif
    
    //
    //  Data to write into the EEPROM.
    //
    unsigned int _pulseLength[] = { 2000U, 27830U, 400U, 1580U, 400U, 3580U, 400U };
    unsigned char _onOrOff[] =    {   1,      0,     1,     0,    1,     0,    1 };
    char numberOfValues = 7;
    
    //--------------------------------------------------------------------------------
    //
    //  Write the default values into EEPROM.
    //
    void SetDefaultValues()
    {
        //
        //  Check if the EEPROM is write-protected.  If it is then unlock the EEPROM.
        //
        if (FLASH_IAPSR_DUL == 0)
        {
            FLASH_DUKR = 0xae;
            FLASH_DUKR = 0x56;
        }
        //
        //  Write the data to the EEPROM.
        //
        char *address = (char *) 0x4000;        //  EEPROM base address.
        *address++ = (char) numberOfValues;
        for (int index = 0; index < numberOfValues; index++)
        {
            *address++ = (char) (_pulseLength[index] & 0xff);
            *address++ = (char) ((_pulseLength[index] >> 8) & 0xff);
            *address++ = _onOrOff[index];
        }
        //
        //  Now write protect the EEPROM.
        //
        FLASH_IAPSR_DUL = 0;
    }
    
    //--------------------------------------------------------------------------------
    //
    //  Main program loop.
    //
    void main()
    {
        SetDefaultValues();
    }
    

    The application simply enables writing to the EEPROM and then writes data to the memory. It also re-enables the write protection at the end of the write operation.

    Verifying the Data

    Testing this application should simply be a case of creating a new project, putting the above in main.c, setting some options and then running the code. The EEPROM data can then be read by ST Visual Develop and verified by hand. After compiling and executing the above code, start ST visual Programmer, connect it to the STM8S Discovery board and download the contents of the EEPROM:

    This does not look correct. Double checking the code against RM0016 – Reference Manual all looks good with the application. So try downloading the EEPROM data again:

    This time the data looks good and the values appear to be correct.

    Downloading the EEPROM data again gave the first set of results. Trying for a fourth thime gave the second set of results. It appears that the correct data is only retrieved every second attempt (for reference, I am using ST Visual Develop version 3.2.8 on Windows 8).

    At this point I decided that the only way to ensure that the data is in fact correct is to write a verification method into the code. The new application becomes:

    //
    //  Write a series of bytes to the EEPROM of the STM8S105C6 and then
    //  verify that the data has been written correctly.
    //
    //  This software is provided under the CC BY-SA 3.0 licence.  A
    //  copy of this licence can be found at:
    //
    //  http://creativecommons.org/licenses/by-sa/3.0/legalcode
    //
    #if defined DISCOVERY
        #include <iostm8S105c6.h>
    #else
        #include <iostm8s103f3.h>
    #endif
    
    //
    //  Data to write into the EEPROM.
    //
    unsigned int _pulseLength[] = { 2000U, 27830U, 400U, 1580U, 400U, 3580U, 400U };
    unsigned char _onOrOff[] =    {   1,      0,     1,     0,    1,     0,    1 };
    char numberOfValues = 7;
    
    //--------------------------------------------------------------------------------
    //
    //  Write the default values into EEPROM.
    //
    void SetDefaultValues()
    {
        //
        //  Check if the EEPROM is write-protected.  If it is then unlock the EEPROM.
        //
        if (FLASH_IAPSR_DUL == 0)
        {
            FLASH_DUKR = 0xae;
            FLASH_DUKR = 0x56;
        }
        //
        //  Write the data to the EEPROM.
        //
        char *address = (char *) 0x4000;        //  EEPROM base address.
        *address++ = (char) numberOfValues;
        for (int index = 0; index < numberOfValues; index++)
        {
            *address++ = (char) (_pulseLength[index] & 0xff);
            *address++ = (char) ((_pulseLength[index] >> 8) & 0xff);
            *address++ = _onOrOff[index];
        }
        //
        //  Now write protect the EEPROM.
        //
        FLASH_IAPSR_DUL = 0;
    }
    
    //--------------------------------------------------------------------------------
    //
    //  Verify that the data in the EEPROM is the same as the data we
    //  wrote originally.
    //
    void VerifyEEPROMData()
    {
        PD_ODR_ODR2 = 1;            //  Checking the data
        PD_ODR_ODR3 = 0;            //  No errors.
        //
        char *address = (char *) 0x4000;        //  EEPROM base address.
        if (*address++ != numberOfValues)
        {
            PD_ODR_ODR3 = 1;
        }
        else
        {
            for (int index = 0; index < numberOfValues; index++)
            {
                unsigned int value = *address++;
                value += (*address++ << 8);
                if (value != _pulseLength[index])
                {
                    PD_ODR_ODR3 = 1;
                }
                if (*address++ != _onOrOff[index])
                {
                    PD_ODR_ODR3 = 1;
                }
            }
        }
        PD_ODR_ODR2 = 0;        // Finished processing.
    }
    
    //--------------------------------------------------------------------------------
    //
    //  Setup port D for data output.
    //
    void SetupPorts()
    {
        //
        //  Initialise Port D.
        //
        PD_ODR = 0;             //  All pins are turned off.
        PD_DDR = 0xff;          //  All bits are output.
        PD_CR1 = 0xff;          //  All pins are Push-Pull mode.
        PD_CR2 = 0xff;          //  Pins can run up to 10 MHz.
    }
    
    //--------------------------------------------------------------------------------
    //
    //  Main program loop.
    //
    void main()
    {
        SetupPorts();
        SetDefaultValues();
        VerifyEEPROMData();
    }
    

    The application uses Port D, pins 2 and 3 to indicate how the verification is proceeding. Pin D2 goes high when the application is verifying the data. Pin D3 is used to indicate if an error is found. Compiling the above and connecting up a scope gives the following output:

    Pin D2 is connected to the yellow channel and pin D3 is connected to the blue channel. The above shows that the verification process starts and no errors are generated.

    Conclusion

    There may only be a small amount of EEPROM storage space available on the STM8S (640 bytes to be precise) but this offers a quick and simple method of storing data which may be needed between system resets/power loses.

    In it’s simplest form, the code required to store the data is trivial only requiring the developer to enable the write operations and then disable after the data has been written successfully.

    In addition to the above I would recommend that some form of checksum value is written into the EEPROM as it is possible that the power is lost as the data is being written into the EEPROM. In this case there are two arrays being written and we may only have written half of the data when the power is lost. This is left as an exercise for the reader.

Transmitting Data Using the STM8S SPI Master Mode

Sunday, June 23rd, 2013

So far in The Way of the Register series we have only looked at SPI from a slave device point of view as we have been working towards creating a Netduino GO! module. For every slave device there must be a master, here we will look at configuring the STM8S to operate in SPI master mode.

The project will look at controlling a TLC5940 in order to emulate the work described in the post TLC5940 16 Channel PWM Driver. We could simply bit-bang the data out to the chip but instead we will use the SPI interface to achieve this.

The project breaks down into the following steps:

  1. Generate the grey scale clock and blank signals
  2. Bit-Bang data out over GPIO pins to create an operational circuit
  3. Convert the data transmission to SPI

See the quoted post for a description of how this chip works and for an explanation of the terminology used.

Generating the Grey Scale Clock and Blank Signals

The TLC5940 generated 4,096 grey scale values by using a PWM counter. Once the counter reaches 4096 pulses it stops until it is told to restart. The Blank pulse acts as a restart signal. This project will be controlling LEDs and so will want to continuously keep the counter running. If we did not keep the counter in the TLC5940 running then the LEDs would light for a short while and then simply turn off and remain off.

The greyscale clock is generated by using the Configurable Clock Output (CCO) pin on the STM8S. This pin simply outputs the clock pulses used to drive the STM8S. Reviewing the data sheet we find that the maximum value for the grey scale clock is 30MHz. Using out standard clock initialisation generates a clock with a frequency of 16MHz (approximately). This is well within the tolerances of the TLC5940. To output this we need to make a simple modification to our standard code, name change the line:

CLK_CCOR = 0;   //  Turn off CCO.

to:

CLK_CCOR = 1;   //  Turn on CCO.

The starting point for our application becomes:

#if defined DISCOVERY
    #include <iostm8S105c6.h>
#elif defined PROTOMODULE
    #include <iostm8s103k3.h>
#else
    #include <iostm8s103f3.h>
#endif
#include <intrinsics.h>

//
//  Setup the system clock to run at 16MHz using the internal oscillator.
//
void InitialiseSystemClock()
{
    CLK_ICKR = 0;                       //  Reset the Internal Clock Register.
    CLK_ICKR_HSIEN = 1;                 //  Enable the HSI.
    CLK_ECKR = 0;                       //  Disable the external clock.
    while (CLK_ICKR_HSIRDY == 0);       //  Wait for the HSI to be ready for use.
    CLK_CKDIVR = 0;                     //  Ensure the clocks are running at full speed.
    CLK_PCKENR1 = 0xff;                 //  Enable all peripheral clocks.
    CLK_PCKENR2 = 0xff;                 //  Ditto.
    CLK_CCOR = 1;                       //  Turn on CCO.
    CLK_HSITRIMR = 0;                   //  Turn off any HSIU trimming.
    CLK_SWIMCCR = 0;                    //  Set SWIM to run at clock / 2.
    CLK_SWR = 0xe1;                     //  Use HSI as the clock source.
    CLK_SWCR = 0;                       //  Reset the clock switch control register.
    CLK_SWCR_SWEN = 1;                  //  Enable switching.
    while (CLK_SWCR_SWBSY != 0);        //  Pause while the clock switch is busy.
}

//
//  Main program loop.
//
void main()
{
    //
    //  Initialise the system.
    //
    __disable_interrupt();
    InitialiseSystemClock();
    __enable_interrupt();
    while (1)
    {
        __wait_for_interrupt();
    }
}

Wiring up the STM8S and connecting the scope to PC4 (CCO output pin) gives the following trace on the scope:

CCO On Scope

CCO On Scope

The trace on the scope has a minimum value of around 680mV and a maximum of 2.48V. In an ideal world this signal should range from 0 to 3.3V (based upon a 3.3V supply). Adding an inverter from a 74HC04 and feeding the signal through one of the gates gives the following trace:

Invertor output on the scope

Inverter output on the scope

This is starting to look a lot better. The next task is to create the Blank signal. There are several ways of doing this. The most automatic way of doing this is to generate a very short PWM pulse using one of the timers in the STM8S. One drawback of this method is that it is more difficult to generate a Blank pulse on demand. Instead we will use the interrupt method described in the same article. Whilst not automatic it is still a trivial task to complete. We simply modify the code from the method to load the counters with 4,096. The code for the GPIO port, timer and interrupt becomes:

//
//  Timer 2 Overflow handler.
//
#pragma vector = TIM2_OVR_UIF_vector
__interrupt void TIM2_UPD_OVF_IRQHandler(void)
{
    PD_ODR_ODR4 = 1;
    PD_ODR_ODR4 = 0;
    TIM2_SR1_UIF = 0;       //  Reset the interrupt otherwise it will fire again straight away.
}

//
//  Setup Timer 2 to generate an interrupt every 4096 clock ticks.
//
void SetupTimer2()
{
    TIM2_PSCR = 0x00;       //  Prescaler = 1.
    TIM2_ARRH = 0x10;       //  High byte of 4096.
    TIM2_ARRL = 0x00;       //  Low byte of 4096.
    TIM2_IER_UIE = 1;       //  Turn on the interrupts.
    TIM2_CR1_CEN = 1;       //  Finally enable the timer.
}

//
//  Setup the output ports used to control the TLC5940.
//
void SetupOutputPorts()
{
    PD_ODR = 0;             //  All pins are turned off.
    PD_DDR_DDR4 = 1;        //  Port D, pin 4 is used for the Blank signal.
    PD_CR1_C14 = 1;         //  Port D, pin 4 is Push-Pull
    PD_CR2_C24 = 1;         //  Port D, Pin 4 is generating a pulse under 2 MHz.
}

Hooking up the scope to PD4 gives the following trace:

Blanking pulses

Blanking pulses

The single pulses are being generated at a frequency of approximately 3.9kHz. A little mental arithmetic dividing the 16MHz clock by 4,096 comes out to about 3,900.

Zooming in on the signal we see:

Single Blanking Pulse

Single Blanking Pulse

This shows that the signal is 125nS wide. This is acceptable as the minimum pulse width given in the data sheet is 20nS.

So at this point we have the 16MHz grey scale clock signal and the Blank pulse being generated every 4,096 clock pulses.

Connecting the TLC5940

The next task is to connect the STM8S to the TLC5940. You should refer to the article TLC5940 16 Channel PWM Driver for more information on the pins and their meaning. For this exercise we will use the following mapping:

STM8S PinTLC5940 Pin
PD4Blank (pin 23)
PD3XLAT (pin 24)
PD2VPRG (pin 27)
PD5Serial data (pin 26)
PD6Serial clock (pin 25)
PC4 (via inverter)GSCLK (pin 18)

You will note that the serial data and clock are currently connected to PD5 and PD6 respectively. Whilst the eventual aim is to communicate with the TLC5940 via SPI, the initial communication will be using Bit-Banging. We will move on to using SPI once the operation of the circuit has been proven using tested technology.

The first changes we will have to make create some #define statements to make the code a little more readable. We also add some storage space for the grey scale and dot correction data.

//
//  Define which pins on Port D will be used as control signals for the TLC5940.
//
//  BLANK - A pulse from low to high causes the TLC5940 to restart the counter
//  XLAT - A high pulse causes the data to be transferred into the DC or GS registers.
//  VPRG - Determines which registers are being programmed, High = DC, Low = GS.
//
#define PIN_BLANK                   PD_ODR_ODR4
#define PIN_XLAT                    PD_ODR_ODR3
#define PIN_VPRG                    PD_ODR_ODR2
//
//  Bit bang pins.
//
#define PIN_BB_DATA                 PD_ODR_ODR5
#define PIN_BB_CLK                  PD_ODR_ODR6
//
//  Values representing the modes for the VPRG pin.
//
#define PROGRAMME_DC                1
#define PROGRAMME_GS                0

//
//  TLC5940 related definitions.
//
#define TLC_NUMBER                  1
#define TLC_DC_BYTES_PER_CHIP       12
#define TLC_DC_BYTES                TLC_NUMBER * TLC_DC_BYTES_PER_CHIP
#define TLC_GS_BYTES_PER_CHIP       24
#define TLC_GS_BYTES                TLC_NUMBER * TLC_GS_BYTES_PER_CHIP

//
//  Next we need somewhere to hold the data.
//
unsigned char _greyScaleData[TLC_GS_BYTES];
unsigned char _dotCorrectionData[TLC_DC_BYTES];

The Bit-Banging methods should look familiar to anyone who has been reading any of the posts in The Way of the Register series.

//--------------------------------------------------------------------------------
//
//  Bit bang data.
//
//  TLC5940 expects the data to be shifted MSB first.  The data
//  is shifted in on the rising edge of the clock.
//
void BitBang(unsigned char byte)
{
    for (short bit = 7; bit >= 0; bit--)
    {
        if (byte &amp; (1 << bit))
        {
            PIN_BB_DATA = 1;
        }
        else
        {
            PIN_BB_DATA = 0;
        }
        PIN_BB_CLK = 1;
        PIN_BB_CLK = 0;
    }
    PIN_BB_DATA = 0;
}

//--------------------------------------------------------------------------------
//
//  Bit bang a buffer of data.
//
void BitBangBuffer(unsigned char *buffer, int size)
{
    for (int index = 0; index < size; index++)
    {
        BitBang(buffer[index]);
    }
}

Related to the Bit-Banging methods are the two methods which will send the grey scale and dot correction data:

//--------------------------------------------------------------------------------
//
//  Send the grey scale data to the TLC5940.
//
void SendGreyScaleData(unsigned char *buffer, int length)
{
    PIN_VPRG = PROGRAMME_GS;
    BitBangBuffer(buffer, length);
    PulseXLAT();
    PulseBlank();
}

//--------------------------------------------------------------------------------
//
//  Send the dot correction buffer to the TLC5940.
//
void SendDotCorrectionData(unsigned char *buffer, int length)
{
    PIN_VPRG = PROGRAMME_DC;
    BitBangBuffer(buffer, length);
    PulseXLAT();
    PulseBlank();
}

We also need a few methods to make the TLC5940 latch the data and also restart the counters:

//--------------------------------------------------------------------------------
//
//  Pulse the Blank pin in order to make the TLC5940 reload the counters and
//  restart timer.
//
void PulseBlank()
{
    PIN_BLANK = 1;
    PIN_BLANK = 0;
}

//--------------------------------------------------------------------------------
//
//  Pulse the XLAT pin in order to make the TLC5940 transfer the
//  data from the latches into the appropriate registers.
//
void PulseXLAT()
{
    PIN_XLAT = 1;
    PIN_XLAT = 0;
}

Next we need to set the initial condition. For this we set the TLC dot correction off and also turn all of the LEDs off:

//--------------------------------------------------------------------------------
//
//  Initialise the TLC5940.
//
void InitialiseTLC5940()
{
    for (int index = 0; index < TLC_DC_BYTES; index++)
    {
        _dotCorrectionData[index] = 0xff;
    }
    for (int index = 0; index < TLC_GS_BYTES; index++)
    {
        _greyScaleData[index] = 0;
    }
    SendDotCorrectionData(_dotCorrectionData, TLC_DC_BYTES);
    SendGreyScaleData(_greyScaleData, TLC_GS_BYTES);
}

The final support method we need to add is the method which sets the brightness of an LED. The brightness is a 12-bit value (0-4095). This means each LED uses 1.5 bytes for the brightness value. The following methods breaks down the value and ensures that the correct bits are set in the grey scale buffer depending upon which LED is being changed:

//--------------------------------------------------------------------------------
//
//  Set the brightness of an LED.
//
void SetLEDBrightness(int ledNumber, unsigned short brightness)
{
    int offset = (ledNumber >> 1) * 3;
    if (ledNumber &amp; 0x01)
    {
        _greyScaleData[offset + 1] = (unsigned char) (_greyScaleData[offset + 1] &amp; 0xf0) | ((brightness & 0x0f00) >> 8);
        _greyScaleData[offset + 2] = (unsigned char) (brightness & 0xff);
    }
    else
    {
        _greyScaleData[offset] = (unsigned char) ((brightness &amp; 0x0ff0) >> 4) &amp; 0xff;
        _greyScaleData[offset + 1] = (unsigned char) ((brightness & 0x0f) >> 4) | (_greyScaleData[offset + 1] & 0x0f);
    }
}

We should also create a similar method for changing the dot correction value for an LED. This is left as an exercise for the reader as we will not be changing this value in this code.

Proving the concept

If we have connected the TLC5940 correctly and our code works we should be able to connect up some LEDs (common anode) to the TLC5940 and change the brightness under program control.

This main program loop slowly increases the brightness of the LEDs. When they are at full brightness they are turned off and the process starts again:

//--------------------------------------------------------------------------------
//
//  Main program loop.
//
void main()
{
    //
    //  Initialise the system.
    //
    __disable_interrupt();
    InitialiseSystemClock();
    SetupOutputPorts();
    SetupTimer2();
    
    InitialiseTLC5940();
    __enable_interrupt();
    //
    //  Main program loop.
    //
    int brightness = 0;
    int counter = 0;
    while (1)
    {
        __wait_for_interrupt();
        counter++;
        if (counter == 20)
        {
            TIM2_CR1_CEN = 0;
            counter = 0;
            for (int index = 0; index < 16; index++)
            {
                SetLEDBrightness(index, brightness);
            }
            SendGreyScaleData(_greyScaleData, TLC_GS_BYTES);
            brightness++;
            if (brightness == 4096)
            {
                brightness = 0;
            }
            TIM2_CR1_CEN = 1;       //  Finally re-enable the timer.
        }
    }
}

If you connect a scope to the cathode of one of the LEDs you will see that the wave form slowly changes over time. At the start, the LED is fully on and the trace on the scope shows a horizontal line, i.e. a constant voltage. As time moves on and the value in the dot correction buffer changes you start to see a PWM signal similar to the following:

PWM Output On Scope 1

PWM Output On Scope 1

This trace shows the signal when the LEDs are a little brighter:

PWM Output On Scope 2

PWM Output On Scope 2

Having arrived here we now know that the circuit has been connected correctly and that the control logic in the main method works. We can now move on to considering what we need to do in order to use SPI in master mode. The aim will be to simply remove the Bit-Banging methods and replace these with an interrupt driven SPI master algorithm.

SPI Master

So now we have a working circuit we need to look at SPI on the STM8S. Firstly let’s remind ourselves of the serial communication parameters for the TLC5940. This chip reads the data on the leading clock edge (CPHA = 1). We have also set the clock idle state to low (CPOL = 0).

It is also advisable to start off using the lowest clock speed for SPI in order to confirm correct operation of the software and circuit. Lower speed are less likely to be subject to interference.

SPI Registers

You should review the previous articles on SPI communication if you are not already familiar with the SPI registers we have used so far. In this post we will only discuss the new settings required to switch from being a SPI slave device to a SPI master device.

SPI_CR1_BR – Baud Rate Control

The SPI baud rate is determined by the master clock frequency and the value in this register. The divisor used to set the baud rate according to the following table:

SPI_CR1_BRDivisor
0002
0014
0108
01116
10032
10164
110128
111256

The SPI baud rate is calculated as fmaster / divisor. So for our master clock speed of 16MHz we get the lowest clock speed of 16,000,000 / 256, or 62,500Hz.

SPI_CR1_MSTR – Master Selection

Setting this bit switches SPI into master mode (see also SPI_CR1_SPE).

Note that the reference for the STM8S also states that this bit (and SPI_CR1_SPE) will only remain set whilst NSS is high. It this therefore essential to connect NSS to Vcc if this device is not being used as a slave device.

Implementing SPI

Using SPI presents us with a small problem, namely the program will have to start to operate in a more asynchronous way. The code presented so far has only one interrupt to be concerned with, namely the timer used to control the Blank signal. Adding SPI to the mix means that we will have to also consider the SPI interrupt as well. It also adds the complication of sending dot correction data followed by grey scale data. This last problem will not be covered here and is left as an exercise for the reader.

The initialisation code merely sets things up for us:

//--------------------------------------------------------------------------------
//
//  Initialise SPI to be SPI master.
//
void SetupSPIAsMaster()
{
    SPI_CR1_SPE = 0;                    //  Disable SPI.
    SPI_CR1_CPOL = 0;                   //  Clock is low when idle.
    SPI_CR1_CPHA = 0;                   //  Capture MSB on first edge.
    SPI_ICR_TXIE = 1;                   //  Enable the SPI TXE interrupt.
    SPI_CR1_BR = 7;                     //  fmaster / 256 (62,500 baud).
    SPI_CR1_MSTR = 1;                   //  Master device.
}

Much of the code should be familiar as it has been used in previous posts discussing SPI slave devices. Not however that we do not enable SPI at this point. We simply set the scene for us to use SPI later.

The SPI data transfers will be controlled by using an interrupt service routine:

//--------------------------------------------------------------------------------
//
//  SPI Interrupt service routine.
//
#pragma vector = SPI_TXE_vector
__interrupt void SPI_IRQHandler(void)
{
    //
    //  Check for an overflow error.
    //
    if (SPI_SR_OVR)
    {
        (void) SPI_DR;                      // These two reads clear the overflow
        (void) SPI_SR;                      // error.
        return;
    }
    if (SPI_SR_TXE)
    {
        //
        //  Check if we have more data to send.
        //
        if (_txBufferIndex == _txBufferSize)
        {
            while (SPI_SR_BSY);
            SPI_CR1_SPE = 0;
            _txBuffer = 0;
            PulseXLAT();
            PulseBlank();
            TIM2_CR1_CEN = 1;
        }
        else
        {
            SPI_DR = _txBuffer[_txBufferIndex++];
        }
    }
}

The main works starts when we have established that the transmit buffer is empty (SPI_SR_TXE is set). If we have more data then we put the byte into the data register (SPI_DR). If we have transmitted all the data we have then we wait for the last byte to complete transmission (SPI_SR_BSY becomes false) before we start to terminate the end of the SPI communication.

In order to send some data we really just need to setup the pointers and counters correctly and then enable SPI. So the SendGreyScaleData method becomes:

//--------------------------------------------------------------------------------
//
//  Send the grey scale data to the TLC5940.
//
void SendGreyScaleData(unsigned char *buffer, int length)
{
    PIN_VPRG = PROGRAMME_GS;
    _txBuffer = buffer;
    _txBufferIndex = 0;
    _txBufferSize = length;
    TIM2_CR1_CEN = 0;
    SPI_CR1_SPE = 1;
}

We also need to have a look at the main program loop as we use the __wait_for_interrupt() method in order to determine when we should start to process the next LED brightness value. We now need to ignore the interrupts when SPI is enabled otherwise the brightness will increase each time the transmit buffer is empty. A crude implementation eliminating the SPI interrupts is:

int brightness = 0;
int counter = 0;
while (1)
{
    __wait_for_interrupt();
    if (!SPI_CR1_SPE)
    {
        counter++;
        if (counter == 20)
        {
            TIM2_CR1_CEN = 0;
            counter = 0;
            for (int index = 0; index < 16; index++)
            {
                SetLEDBrightness(index, brightness);
            }
            SendGreyScaleData(_greyScaleData, TLC_GS_BYTES);
            brightness++;
            if (brightness == 4096)
            {
                brightness = 0;
            }
            TIM2_CR1_CEN = 1;       //  Finally re-enable the timer.
        }
    }
}

Making these changes and running the code shows that the system operated as before.

Increasing the Baud Rate

As noted earlier, the baud rate has been set low in order to reduce the chance of any problems being experienced due to interference. Now we have established that using SPI communication is possible and the circuit works as before we can start to increase the baud rate. Using our 16MHz clock we find we have the following baud rates which are theoretically possible:

SPI_CR1_BRDivisorSPI Frequency
00028 MHz
00144 MHz
01082 MHz
011161 MHz
10032500 KHz
10164250 KHz
110128125 KHz
11125662.5 KHz

A little experimentation is called for. Being ambitious I started with a clock frequency of 1MHz. This resulted in a flickering effect on the LED display. So, 1MHz is too ambitious, let’s start to reduce the frequency. I finally settled on 250 KHz as this allowed the circuit to function as before.

Conclusion

Using SPI master for data transmission was not as difficult as I originally thought. To make this application complete there are a few tasks to follow up on, namely:

  1. Receiving data over SPI
  2. Create the method to allow setting the dot correction values
  3. Transmitting buffers from a queue
  4. Minor tidying up of the timer control

The use of SPI here actually increased the time taken (597uS Bit-Banging c.f. 795uS for 250 KHz SPI) to reliably send the grey scale data to the TLC5940. I suspect that the time can be decreased if the circuit was taken from breadboard and put onto a PCB manufactured for the purpose. The breadboard for this circuit currently looks like this:

Bread Board And Flying Leads

Bread Board And Flying Leads

As you can see, there is a lot of opportunity for interference with all those flying leads.

While the time taken might have increased, the load on the microcontroller will have decreased as the SPI method is interrupt driven. The actual transmission is off-loaded to the microcontrollers dedicated circuitry.

As usual, the source code for this project is available to download.

Making a Netduino GO! Module – Stage 2 – Connect the GO! to the Breadboard

Friday, April 12th, 2013

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 &amp; PC4 initialised for output.
    PC_CR1 = 0x18;          //  PC3 &amp; PC4 Push-Pull outputs
    PC_CR2 = 0x18;          //  PC3 &amp; 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!

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.

STM32F4 Clocks

Thursday, March 28th, 2013

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:

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

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

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)

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)

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)

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

STM32 – Simple GPIO and Some Flashing LEDs

Saturday, March 23rd, 2013

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

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:

Bit ValuesDescription
00Input
01General purpose output
10Alternate function
11Analog

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:

PortReset Value
A0xA800 0000
B0x0000 0280
All others0x0000 0000

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.

Bit ValueDescription
0Push/pull output
1Open drain output

The default reset value for all of the GPIOx_TYPER registers is 0x0000 0000 meaning that all ports are configured for push/pull output.

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:

Bit ValuesDescription
002 MHz Low speed
0125 MHz Medium speed
1050 MHz Fast speed
11100 MHz High speed on 30pF
80 MHz High speed on 15 pF

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:

Bit ValuesDescription
00No pull-up or pull-down resistor
01Pull-up resistor
10Pull-down resistor
11Reserved

The reset values for the registers are:

PortReset Value
A0x6400 0000
B0x0000 0100
All others0x0000 0000

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.

Bit ValueDescription
0High logic value
1Low logic value

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:

Bit ValueDescription
0High logic value
1Low logic value

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

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:

Pin NumberColour
12Green
13Orange
14Red
5Blue

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.

STM8S SPI Slave (Part 3) – Making a Go Module

Monday, November 26th, 2012

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:

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:

private Guid _moduleGuid = new Guid(new byte[] { 0x80, 0x39, 0xe8, 0x2b, 0x55, 0x58, 0xeb, 0x48, 0xab, 0x9e, 0x48, 0xd3, 0xfd, 0xae, 0x8c, 0xee });

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

      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

      SystemCompatible?
      STM8S103F3 (Breadboard)
      Variable Lab Protomodule
      STM8S Discovery