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

Did you know...

Serial Wombat Pin Mode Software Development Kit Pin Mode Overview

A pin mode consists of two functions that you provide, compiled into a framework that the Wombat can understand:

• A function which is called every time an initialize pin mode command (200 to 209) is called with your SDK pin mode number (0xF0 to 0xF7)
• A function which is called every frame to update the status of a pin set to your mode.

By default, these two functions are placed in user_code.c . Inside user_code.c you'll find the following sample functions:

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

}

The first function, init_user_code is called every time a pin configuration message is called with your pin mode number (by default 0xF0). The 8 byte message itself is stored in the global byte array rxbuffer. You can see that the example is set up to process two different messages, one starting with CONFIGURE_CHANNEL_MODE_0 (200) and one starting with CONFIGURE_CHANNEL_MODE_1 (201). Your pin mode may only need to process one of these messages, or you may want to add 8 more in additional if statements. The example includes two just to show how it is done.

The second function, update_user_code is called each frame (by default 1ms). This is where you put your code to update the pin.

Let's create a very simple pin mode. All this mode will do is toggle a pin high and low, over and over.

Example 1: Toggling a pin

In order to achieve this, we'll use three different functions which are built into the Serial Wombat firmware: vpin_read, vpin_high, and vpin_low. These functions do pretty much what you'd expect. vpin_read returns 0 or 1 depending on the current state of the pin. vpin_low sets a pin low, and vpin_high sets a pin high.

You may ask, why "vpin" and not just "pin"? The answer is that the "v" stands for virtual. These functions will act on whatever the currently selected pin is. That is, if you create a new pin mode numbered 0xF0, and assign pin 20 to your mode, then vpin_low will set pin 20 low when your mode is serviced. If you set pin 14 to your mode, then it will set pin 14 low. You can set both pin 20 and pin 14 to your new mode if you like. Then your mode will be called twice in each frame. The first time it will service pin 14, and the second time it will service pin 20. Many functions act this way on whatever the current virtual pin is. That way, you can write pin modes in a way where they will work on any pin, rather than just one.

On to the code:

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 (vpin_read())
        {
                vpin_low();  // If the pin was high, set it low
        }
        else
        {
                vpin_high(); // If the pin was low, set it high
        }

}

All of the changes are made in the update_user_code section. Since this is such a simple function, there's no user configurable parameters to set. So we don't have to put anything in init_user_code. The Wombat Firmware will take care of setting the configured pin to this mode before init_user_code is called, and will make sure the update function is called every frame to service the pin.

Once we've saved our changes, we'll build them using the free MPLAB IDE and C18 Student Edition compiler provided by Microchip. This example assumes you've already downloaded and installed these tools.

Open the workspace provided with the SDK zip file under file..open workspace. You're looking for the file sdk_w4620.mcw. You should get a variety of open windows, including your code:

Now, press the "Build All" button. It looks like a bucket with two arrows pointing down into it. You should see MPLAB building your files.

If all goes well, you'll get a BUILD SUCCEEDED message in the output window. If you look in the SDK directory, you should find a file sdk_w4620.hex with the current date and time. This file contains the compiled and linked machine code you just generated.

Now, we need to trim the .hex file to only the parts we want, and convert it into binary form for the Wombat. A utility for doing this is provided with the SDK. Open a command prompt and cd to the sdk directory. Run the program sdkextract.exe with the name of the incoming hex file, and the name of the dedired output file:

The output file (in this case, sdk_w4620.bin) can now be downloaded to the Wombat using Xmodem. The bin file should be downloaded to address 0xC000. See the protocol page for information about Xmodem downloads, or use the WombatPanel sample application to do this download.

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 transitions in each 1ms frame.