5. Software Reference

RabbitCore RCM4500W
User's Manual

5. Software Reference

Dynamic C is an integrated development system for writing embedded software. It runs on an IBM-compatible PC and is designed for use with single-board computers and other devices based on the Rabbit microprocessor. Chapter 5 describes the libraries and function calls related to the RCM4510W.

5.1 More About Dynamic C

Dynamic C has been in use worldwide since 1989. It is specially designed for programming embedded systems, and features quick compile and interactive debugging. A complete reference guide to Dynamic C is contained in the Dynamic C User's Manual.

You have a choice of doing your software development in the flash memory or in the static SRAM included on the RCM4510W. The flash memory and SRAM options are selected with the Options > Program Options > Compiler menu.

The advantage of working in RAM is to save wear on the flash memory, which is limited to about 100,000 write cycles. The disadvantage is that the code and data might not both fit in RAM.

NOTE Do not depend on the flash memory sector size or type in your program logic. The RCM4510W and Dynamic C were designed to accommodate flash devices with various sector sizes in response to the volatility of the flash-memory market.

Developing software with Dynamic C is simple. Users can write, compile, and test C and assembly code without leaving the Dynamic C development environment. Debugging occurs while the application runs on the target. Alternatively, users can compile a program to an image file for later loading. Dynamic C runs on PCs under Windows NT and later—see Rabbit's Technical Note TN257, Running Dynamic C® With Windows Vista®, for additional information if you are using a Dynamic C under Windows Vista. Programs can be downloaded at baud rates of up to 460,800 bps after the program compiles.

Dynamic C has a number of standard features.

Full-feature source and/or assembly-level debugger, no in-circuit emulator required.

Royalty-free TCP/IP stack with source code and most common protocols.

Hundreds of functions in source-code libraries and sample programs:

u Exceptionally fast support for floating-point arithmetic and transcendental functions.

u RS-232 and RS-485 serial communication.

u Analog and digital I/O drivers.

u I²C, SPI, GPS, file system.

u LCD display and keypad drivers.

Powerful language extensions for cooperative or preemptive multitasking

Loader utility program to load binary images into Rabbit targets in the absence of Dynamic C.

Provision for customers to create their own source code libraries and augment on-line help by creating "function description" block comments using a special format for library functions.

Standard debugging features:

u Breakpoints—Set breakpoints that can disable interrupts.

u Single-stepping—Step into or over functions at a source or machine code level, µC/OS-II aware.

u Code disassembly—The disassembly window displays addresses, opcodes, mnemonics, and machine cycle times. Switch between debugging at machine-code level and source-code level by simply opening or closing the disassembly window.

u Watch expressions—Watch expressions are compiled when defined, so complex expressions including function calls may be placed into watch expressions. Watch expressions can be updated with or without stopping program execution.

u Register window—All processor registers and flags are displayed. The contents of general registers may be modified in the window by the user.

u Stack window—shows the contents of the top of the stack.

u Hex memory dump—displays the contents of memory at any address.

u STDIO window—printf outputs to this window and keyboard input on the host PC can be detected for debugging purposes. printf output may also be sent to a serial port or file.

5.2 Dynamic C Function Calls

5.2.1 Digital I/O

The RCM4510W was designed to interface with other systems, and so there are no drivers written specifically for the Rabbit 4000 I/O. The general Dynamic C read and write functions allow you to customize the parallel I/O to meet your specific needs. For example, use
WrPortI(PEDDR, &PEDDRShadow, 0x00);
to set all the Port E bits as inputs, or use
WrPortI(PEDDR, &PEDDRShadow, 0xFF);
to set all the Port E bits as outputs.

When using the external I/O bus on the Rabbit 4000 chip, add the line
#define PORTA_AUX_IO    // required to enable external I/O bus
to the beginning of any programs using the external I/O bus.

The sample programs in the Dynamic C SAMPLES/RCM4500W folder provide further examples.

5.2.2 Serial Communication Drivers

Library files included with Dynamic C provide a full range of serial communications support. The RS232.LIB library provides a set of circular-buffer-based serial functions. The PACKET.LIB library provides packet-based serial functions where packets can be delimited by the 9th bit, by transmission gaps, or with user-defined special characters. Both libraries provide blocking functions, which do not return until they are finished transmitting or receiving, and nonblocking functions, which must be called repeatedly until they are finished, allowing other functions to be performed between calls. For more information, see the Dynamic C Function Reference Manual and Technical Note TN213, Rabbit Serial Port Software.

5.2.3 User Block

Certain function calls involve reading and storing calibration constants from/to the simulated EEPROM in flash memory located at the top 2K of the reserved user block memory area (3800–39FF). This leaves the address range 0–37FF in the user block available for your application.

These address ranges may change in the future in response to the volatility in the flash memory market, in particular sector size. The sample program USERBLOCK_INFO.C in the Dynamic C SAMPLES\USERBLOCK folder can be used to determine the version of the ID block, the size of the ID and user blocks, whether or not the ID/user blocks are mirrored, the total amount of flash memory used by the ID and user blocks, and the area of the user block available for your application.

The USERBLOCK_CLEAR.C sample program shows you how to clear and write the contents of the user block that you are using in your application (the calibration constants in the reserved area and the ID block are protected).

5.2.4 SRAM Use

The RCM4510W module has a battery-backed data SRAM and a program-execution SRAM. Dynamic C provides the protected keyword to identify variables that are to be placed into the battery-backed SRAM. The compiler generates code that maintains two copies of each protected variable in the battery-backed SRAM. The compiler also generates a flag to indicate which copy of the protected variable is valid at the current time. This flag is also stored in the battery-backed SRAM. When a protected variable is updated, the "inactive" copy is modified, and is made "active" only when the update is 100% complete. This assures the integrity of the data in case a reset or a power failure occurs during the update process. At power-on the application program uses the active copy of the variable pointed to by its associated flag.

The sample code below shows how a protected variable is defined and how its value can be restored.
main() {
   protected int state1, state2, state3;
   ...
   _sysIsSoftReset();    // restore any protected variables
Additional information on protected variables is available in the Dynamic C User's Manual.

5.2.5 RCM4510W Cloning

The RCM4510W does not have a pull-up resistor on the PB1 (CLKA) line of the programming port. Because of this, the procedure to generate clones from the RCM4510W differs from that used for other RabbitCore modules and single-boards computers. You must set the CL_FORCE_MASTER_MODE macro to 1 in the Dynamic C LIB\Rabbit4000\BIOSLIB\CLONECONFIG.LIB library to use the RCM4510W as a master for cloning. An RCM4510W master will not run the application, and further debugging is not possible as long as the CL_FORCE_MASTER_MODE macro is set to 1. Any cloned RCM4510W modules will be "sterile," meaning that they cannot be used as a master for cloning. To develop and debug an application on an RCM4510W, comment out the CL_FORCE_MASTER_MODE macro or set it to 0.

NOTE Instead of defining this macro is your application, you may simply add the line CL_FORCE_MASTER_MODE=1 under the Dynamic C Options > Project Options "Defines" tab, then click OK. When you recompile your program, this will have the same effect as setting the macro to 1 within the CLONECONFIG.LIB library.

See Technical Note TN207, Rabbit Cloning Board, for additional information on Rabbit's cloning board and how cloning is done.

5.2.5.1 Including Firmware Update in Cloned Application

If you include the firmware update in the master RCM4510W program, clone this program to an RCM4510W clone, and then let that program run on the clone, then the firmware update will fail unless you remove the cloning cable from the clone before the firmware update begins.

To avoid this failure, Rabbit recommends that you include code in the master program that is to be cloned to check the firmware version when the RCM4510W resets or boots up. The reset or boot-up will happen as a matter of course once the cloning cable is removed and the RCM4510W clone operates in the Run Mode for the first time. The firmware version can be checked by calling xbee_init() — if an error returns, the firmware update will happen successfully since the cloning cable is no longer attached, and if there is no error returned, the firmware is already up-to-date and the RCM4510W clone will reset or boot up normally.

5.2.6 ZigBee Drivers

The ZigBee drivers are located in the LIB\Rabbit4000\XBee folder. Complete information on these libraries and the ZigBee function calls is provided in Section 6.4.

5.2.7 Prototyping Board Function Calls

The function calls described in this section are for use with the Prototyping Board features. The source code is in the Dynamic C LIB\Rabbit4000\RCM4xxx\RCM45xxW.LIB library if you need to modify it for your own board design.

Other generic functions applicable to all devices based on Rabbit microprocessors are described in the Dynamic C Function Reference Manual.

5.2.7.1 Board Initialization

brdInit

void brdInit(void);

Description

Call this function at the beginning of your program. This function initializes Parallel Ports A through E for use with the Prototyping Board.
Summary of Initialization
1. I/O port pins are configured for Prototyping Board operation.

2. Unused configurable I/O are set as tied outputs.

3. RS-232 is not enabled.

4. LEDs are off.

5. The slave port is disabled.

Return Value

None.

5.2.7.2 Alerts

These function calls can be found in the Dynamic C LIB\Rabbit4000\RCM4xxx\RCM4xxx.LIB library.

timedAlert

void timedAlert(unsigned long timeout);

Description

Polls the real-time clock until a timeout occurs. The RCM4510W will be in a low-power mode during this time. Once the timeout occurs, this function call will enable the normal power source.

Parameter

timeout
the duration of the timeout in seconds

Return Value

None.

See Also
brdInit
digInAlert

void digInAlert(int dataport, int portbit, int value, unsigned long timeout);

Description

Polls a digital input for a set value or until a timeout occurs. The RCM4510W will be in a low-power mode during this time. Once a timeout occurs or the correct byte is received, this function call will enable the normal power source and exit.

Parameters

dataport
the input port data register to poll (e.g., PADR)

portbit
the input port bit (0–7) to poll

value
the value of 0 or 1 to receive

timeout
the duration of the timeout in seconds (enter 0 for no timeout)

Return Value

None.

5.2.8 Auxiliary I/O Pins Function Calls

The function calls described in this section are for use with the pins on the auxiliary I/O header at J4. The source code is in the Dynamic C LIB\Rabbit4000\XBee\XBEE_API.LIB library if you need to modify it for your own board design.

The sample programs in the Dynamic C SAMPLES\XBee folder illustrate the use of the function calls.

zb_io_init

int zb_io_init(void);

Description

Initializes the I/O on the XBee RF module. The default behavior for each pin is predefined, but may be overridden before the #use XBEE_API.LIB statement or by calling the appropriate macro.

J4 Pin Dynamic C Name Functionality Default Configuration State Pull-Up Mask Bit

1

DIO_00

Analog Input or Digital I/O

Analog Input

Not Applicable

4

2

DIO_01

Analog Input or Digital I/O

Analog Input

Not Applicable

3

3

DIO_02

Analog Input or Digital I/O

Analog Input

Not Applicable

2

4

DIO_03

Analog Input or Digital I/O

Analog Input

Not Applicable

1

6

DIO_12

Digital I/O

Digital Input

Pulled Up 30 kW

10

10

DIO_05

Digital I/O

Digital Output

Default High

8

11

DIO_04

Digital I/O

Digital Output

Default High

0

13

DIO_10

Digital I/O

Digital Output

Default Low

11

14

DIO_11

Digital I/O

Digital Input

Pulled Up 30 kW

12

zb_io_init (cont'd)

The pins are configured as analog inputs or as digital I/O using the following macros as examples before #use XBEE_API.LIB.
#define DIO_00 XBEE_IO_CONF_ANAIN       // bit 4
#define DIO_01 XBEE_IO_CONF_ANAIN       // bit 3
#define DIO_02 XBEE_IO_CONF_ANAIN       // bit 2
#define DIO_03 XBEE_IO_CONF_ANAIN       // bit 1
#define DIO_12 XBEE_IO_CONF_DIGIN       // bit 10
#define DIO_05 XBEE_IO_CONF_DIGOUT_HIGH // bit 8
#define DIO_04 XBEE_IO_CONF_DIGOUT_HIGH // bit 0
#define DIO_10 XBEE_IO_CONF_DIGOUT_LOW  // bit 11
#define DIO_11 XBEE_IO_CONF_DIGIN       // bit 12
NOTE The mask order is different than for DIO_INPUTS. While all pins can be configured as either inputs or outputs, only DIO_00 – DIO_03 can be configured as analog inputs.

RETURN VALUE

0 — success.
¹0 — one of the error codes returned by zb_API_ATCmdResponse()

5.2.8.1 Digital I/O

zb_dio_in

int zb_dio_in(int dio);

Description

Reads the logic state of a pin configured as a digital input pin. This value corresponds to the dio number.

Parameters

dio
the Dynamic C digital input pin number (0 – ZB_MAX_PIN, valid values are 0–5, 10–12) set up in zb_io_init().

NOTE The pin number is not the same as the DIO_xx macros described in zb_io_init(), which are used to configure the function of the pin only.

Return Value

0 or 1 — logic state.
–EINVAL — error (pin not configured as a digital input).

zb_dio_out

int zb_dio_out(int dio, int value);

Description

Sets the digital output value.

Parameters

dio
the Dynamic C digital output pin number (0 – ZB_MAX_PIN, valid values are 0–5, 10–12) set up in zb_io_init().

value
the logic level (0 or 1) the pin is set to.

NOTE The pin number is not the same as the DIO_xx macros described in zb_io_init(), which are used to configure the function of the pin only.

Return Value

0 — success.
–EINVAL — error (pin not configured as a digital output).

5.2.8.2 Analog Inputs

zb_adc_in

int zb_adc_in(int dio);

Description

Reads the analog input on the designated pin and return its 10-bit value. To convert the reading to millivolts perform the following calculation.
AD (mV) = (ADIO reading / 1023) × 1200 mV

Parameter

dio
the Dynamic C analog input pin number (0–3) set up in zb_io_ init().

NOTE The pin number is not the same as the DIO_xx macros described in zb_io_init(), which are used to configure the function of the pin only.

Return Value

0–1023 — valid data.
–EINVAL — error (pin not configured as an analog input).

5.3 Upgrading Dynamic C

Dynamic C patches that focus on bug fixes are available from time to time. Check the Web site www.rabbit.com/support/ for the latest patches, workarounds, and bug fixes.

5.3.1 Add-On Modules

Starting with Dynamic C version 10.40, Dynamic C includes the popular µC/OS-II real-time operating system, point-to-point protocol (PPP), FAT file system, RabbitWeb, and other select libraries. Rabbit also offers for purchase the Rabbit Embedded Security Pack featuring the Secure Sockets Layer (SSL) and a specific Advanced Encryption Standard (AES) library.

In addition to the Web-based technical support included at no extra charge, a one-year telephone-based technical support subscription is also available for purchase.

Visit our Web site at www.rabbit.com for further information and complete documentation.

J4 Pin	Dynamic C Name	Functionality	Default Configuration	State	Pull-Up Mask Bit
1	`DIO_00`	Analog Input or Digital I/O	Analog Input	Not Applicable	4
2	`DIO_01`	Analog Input or Digital I/O	Analog Input	Not Applicable	3
3	`DIO_02`	Analog Input or Digital I/O	Analog Input	Not Applicable	2
4	`DIO_03`	Analog Input or Digital I/O	Analog Input	Not Applicable	1
6	`DIO_12`	Digital I/O	Digital Input	Pulled Up 30 kW	10
10	`DIO_05`	Digital I/O	Digital Output	Default High	8
11	`DIO_04`	Digital I/O	Digital Output	Default High	0
13	`DIO_10`	Digital I/O	Digital Output	Default Low	11
14	`DIO_11`	Digital I/O	Digital Input	Pulled Up 30 kW	12

Rabbit—A Digi International Brand
www.rabbit.com