Serial Wombat
a general-purpose digital interface device for hobbyists, engineers and students

Did you know...

Serial Wombat Pin Mode Software Development Kit Example 2: Persistent Data

In example 1, we created a simple example which toggled a pin every frame. In Example 2, we will introduce Persistent Pin data area. This area consists of 16 bytes for each pin. It is defined as follows in types.h in the sdk folder:

#define uint8 unsigned char
#define uint16 unsigned int 

typedef union _persistent_data{
      uint8 bytes[16];

      struct generic_n {
             uint8 bytes[8];
             uint16 buffer;
             uint8 mode; 
             uint8 internal_use[4];
             } generic;

             struct user_mode_n{
             uint8 somedata;
             }somepinmode;

}persistent_data_t

This 16 byte structure is broken into multiple structures for convenience through the use of a union. This application is a textbook application of the C union construct, since it is not known until run-time (when a pin is configured) what the 16 bytes will represent. If you're not familliar with unions, grab a C textbook and read up. They're important for Wombat Pin Mode development.

There are three main items in the union above:

• The first is a simple 16 byte array. Any of the 16 bytes may be accessed using this array.
• The second is a generic structure which outlines the locations of the data used for persistent storage: 8 bytes of mode-specific data, two bytes for the pin's public data area, 1 byte to indicate the pin's mode, and 4 bytes which are reserved for internal Wombat use (these pins are used for things like software PWM generation, off board D/As or digital Pots, etc)
• The third is used to define the 8 custom bytes for a particular pin mode. By adding multiple structures of this fashion, many different pin modes can be described. These structures may contain between 1 and 8 bytes. Using more than 8 bytes will cause conflicts with the other structures in the union, and must be avoided.

Before a pin is serviced, it's persistent data is copied out of the array of persistent pin data to a single static variable, called tp (for temporary pin). After the pin is serviced the data is copied back to the array.

Geeky explanation; Skip this part if you want:

Copying the persistent data from the array to a fixed address structure allows a great increase in efficency and a great reduction in code size for the typical pin mode. This is due to the fact that the C18 / 18F4620 combination used for the Wombat is relatively inefficient at indexed (calculated address) addressing. The short reason for this is that the address written to in the following C command:

tp.mypinmode.somedata = 7;

can be calculated by the compiler at compile time since tp is at a fixed address, and .mypinmode.somedata is at some constant offset from the beginning of tp . However, if rather than using the tp structure, we tried accessing the array with the pin number:

persistent_data[pin_number].mypinmode.somedata = 7;

then the compiler would have to calculate the address by multiplying pin_number by 16 (the size of the structure) then add that to the starting address of the array, then add that to the offset into the array. This address would then be put in the 18F4620's indexed address registers so that the value could be set. The first code example would take less than 5 assembly instructions. The second code example would take more than a dozen.

The copy routines are written in assembly code and can take advantage of a few optimizations (such as copy and post increment pointer operations) which are available on the 18F4620.

Example 2 Code: Toggling a pin high for 10 frames, low for 20 frames.

In this example we need one piece of consistent data: a counter which ranges from 0 to 29, then resets to 0. When the counter is reset, we'll set the pin high. When it reaches 10, we'll set the pin low. As before, there is no user configurable portion to this pin mode, so the initialization will remain blank.

On to the code:

In types.h:

typedef union _pin_register_t{
      uint8 bytes[16];

      struct generic_n {
             uint8 bytes[8];
             uint16 buffer;
             uint8 mode;
             uint8 hw_mode;
             uint8 duty_cycle;
             uint8 hw_counter;
             uint8 hw_support;
             } generic;

      struct example2_n{
              uint8 counter;
             } example2;


} pin_register_t;

in user_code.c:

void init_user_code (void)
{
        if (rxbuffer[0] == CONFIGURE_CHANNEL_MODE_0)
        {
                //Do something here in response to a 200 command

        }
        else if (rxbuffer[0] == CONFIGURE_CHANNEL_MODE_1)
        {
                //Do something else here in response to a 201 command
        }

}

void update_user_code()
{
        //This function is called periodically, after the first time
        //an init function for the pin is called
        if (tp.example2.counter == 0)
        {
                vpin_high();
        }
        else if (tp.example2.counter == 10)
        {
                vpin_low();
        }

        ++tp.example2.counter;

        if (tp.example2.counter == 30)
        {
            tp.example2.counter = 0;
        }


}

As before in example 1, build the project, then run it through sdkextract.exe. Download using Xmodem. Once you've downloaded the pin mode into the Wombat, issue the command

200 20 0xF0 0x55 0x55 0x55 0x55 0x55

To cause pin 20 to be configured to your new pin mode:

(note that in the picture above, the WombatPanel application will automatically pad messages shorter than 8 bytes with 0x55's.)

Attaching an oscilloscope to pin 20 shows the following:

This shows that our sample mode is working. As expected, the pin outputs a 10ms high, 20 ms low waveform..