RabbitCore RCM3700
User's Manual
PREV INDEX NEXT

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 Rabbit Semiconductor single-board computers and other single-board computers based on the Rabbit microprocessor. Chapter 5 describes the libraries and function calls related to the RCM3700.

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 and in the Dynamic C Function Reference Manual.

You have a choice of doing your software development in the flash memory or in the SRAM included on the RCM3700. The flash memory and SRAM options are selected with the 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 An application can be compiled in RAM, but cannot run standalone from RAM after the programming cable is disconnected. All standalone applications can only run from flash memory.
NOTE Do not depend on the flash memory sector size or type in your program logic. The RCM3700 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 95 and later. 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. Some of these standard features are listed below.

5.2 Dynamic C Functions

The functions described in this section are for use with the Prototyping Board features. The source code is in the RCM37xx.LIB library in the Dynamic C SAMPLES\RCM3700 or the SAMPLES\RCM3720 folder, depending on which Prototyping Board you will be using, 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.1 Board Initialization

void brdInit (void);


Call this function at the beginning of your program. This function initializes Parallel Ports A through G for use with the RCM3700 Prototyping Board or the RCM3720 Prototyping Board.
The brdInit function is set up to a default I/O configuration based on the RabbitCore module detected at compile time:

• Any RCM3700 RabbitCore module (except the RCM3720) will have its I/O ports configured for an RCM3700 Prototyping Board.

• An RCM3720 RabbitCore module will have its I/O ports configured for an RCM3720 Prototyping Board.

You may override these default settings to run an RCM3720 RabbitCore module on the RCM3700 Prototyping Board or to run another RCM3700 RabbitCore module on the RCM3720 Prototyping Board by adding the following macro to the program you will be running.

• To run an RCM3720 RabbitCore module on an RCM3700 Prototyping Board, add the following macro at the top of the program you will be running.

Sample programs that are specifically designed for the RCM3700 Prototyping Board already have this macro included. When you run a sample program designed for the RCM3700 Prototyping Board on an RCM3720, a warning message will be displayed to inform you of that. You can disable the warning by commenting out the line indicated by the compiler.

• To run an RCM3700 RabbitCore module (other than the RCM3720) on an RCM3720 Prototyping Board, add the following macro at the top of the program you will be running.

Summary of Initialization

1. I/O port pins are configured for Prototyping Board operation.

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

3. The LCD/keypad module is disabled.

4. RS-485 is not enabled.

5. RS-232 is not enabled.

6. The IrDA transceiver is disabled.

7. LEDs are off.

8. The A/D converter is reset and SCLKB is to 57,600 bps (RCM3700 Prototyping Board only).

9. The A/D converter calibration constants are read (this function cannot run in RAM) (RCM3700 Prototyping Board only).

10. Ethernet select is disabled.

11. Serial flash select is disabled.

CAUTION:
 Pin PB7 is connected as both switch S2 and as an external I/O bus on the RCM3700 Prototyping Board. Do not use S2 when the LCD/keypad module is installed.

CAUTION:
 Pins PC1 and PG2 are tied together, and pins PC3 and PG3 are tied together on the RCM3700 RabbitCore module. Both pairs of pins are connected to the IrDA transceiver and to the RS-232 transceiver via serial ports on the RCM3700 Prototyping Board. Do not enable both transceivers on the RCM3700 Prototyping Board at the same time.

Return Value
None.

5.2.2 Analog Inputs

NOTE The function calls for the A/D converter in this section will work only with the RCM3700 Prototyping Board.

unsigned int anaInConfig(unsigned int instructionbyte, unsigned int cmd, long baud);


Use this function to configure the ADS7870 A/D converter. This function will address the ADS7870 in Register Mode only, and will return error if you try the Direct Mode. Section B.1.5 provides additional addressing and command information for the ADS7870 A/D converter.
ADS7870 Signal ADS7870 State RCM3700 Function/State
LN0
Input
AIN0
LN1
Input
AIN1
LN2
Input
AIN2
LN3
Input
AIN3
LN4
Input
AIN4
LN5
Input
AIN5
LN6
Input
AIN6
LN7
Input
AIN7
/RESET
Input
Board reset device
RISE/FALL
Input
Pulled up for SCLK active on rising edge
PIO0
Input
Pulled down
PIO1
Input
Pulled down
PIO2
Input
Pulled down
PIO3
Input
Pulled down
CONVERT
Input
Pulled down
BUSY
Output
PD1 pulled down; logic high state converter is busy
CCLKCNTRL
Input
Pulled down; 0 state sets CCLK as input
CCLK
Input
Pulled down; external conversion clock
SCLK
Input
PB0; serial data transfer clock
SDI
Input
PD4; 3-wire mode for serial data input
SDO
Output
PD5; serial data output /CS driven
/CS
Input
PD2 pulled up; active-low enables serial interface
BUFIN
Input
Driven by VREF; reference buffer amplifier
VREF
Output
Connected to BUFIN
BUFOUT
Output
VREF output

Parameters
instructionbyte is the instruction byte that will initiate a read or write operation at 8 or 16 bits on the designated register address. For example,
cmd refers to the command data that configure the registers addressed by the instruction byte. Enter 0 if you are performing a read operation. For example,
baud is the serial clock transfer rate of 9600 to 57,600 bps. baud must be set the first time this function is called. Enter 0 for this parameter thereafter, for example,
Return Value
0 on write operations,
data value on read operations
See Also

unsigned int anaInDriver(unsigned int cmd, unsigned int len);


Reads the voltage of an analog input channel by serial-clocking an 8-bit command to the ADS7870 A/D converter by the Direct Mode method. This function assumes that Mode1 (most significant byte first) and the A/D converter oscillator have been enabled. See anaInConfig() for the setup.
The conversion begins immediately after the last data bit has been transferred. An exception error will occur if Direct Mode bit D7 is not set.
Parameters
cmd contains a gain code and a channel code as follows.

D7—1; D6–D4—Gain Code; D3–D0—Channel Code

Use the following calculation and the tables below to determine cmd:
Gain Code Multiplier
0
x1
1
x2
2
x4
3
x5
4
x8
5
x10
6
x16
7
x20

Channel Code Differential Input Lines Channel Code Single-Ended Input Lines1 4–20 mA Lines
0
+AIN0 -AIN1
8
AIN0
AIN0*
1
+AIN2 -AIN3
9
AIN1
AIN1*
2
+AIN4 -AIN5
10
AIN2
AIN2*
32
+AIN6 -AIN7
11
AIN3
AIN3
4
-AIN0 +AIN1
12
AIN4
AIN4
5
-AIN2 +AIN3
13
AIN5
AIN5
6
-AIN4 +AIN5
14
AIN6
AIN6
7*
-AIN6 +AIN7
15
AIN7
AIN7*
1 Negative input is ground.
2 Not accessible on RCM3700 Prototyping Board

len, the output bit length, is always 12 for 11-bit conversions
Return Value
A value corresponding to the voltage on the analog input channel:

0–2047 for 11-bit conversions (bit 12 for sign)
-1 overflow or out of range
-2 conversion incomplete, busy bit timeout

See Also

unsigned int anaIn(unsigned int channel, int opmode, int gaincode);


Reads the value of an analog input channel using the direct method of addressing the ADS7870 A/D converter. The A/D converter is enabled the first time this function is called—this will take approximately 1 second to ensure that the A/D converter capacitor is fully charged.
Parameters
channel is the channel number (0 to 7) corresponding to ADC_IN0 to ADC_IN7
opmode is the mode of operation:

SINGLE—single-ended input
DIFF—differential input
mAMP—4–20 mA input

channel SINGLE DIFF mAMP
0
+AIN0
+AIN0 -AIN1
+AIN01
1
+AIN1
+AIN1 -AIN0*
+AIN1*
2
+AIN2
+AIN2 -AIN3
+AIN2*
3
+AIN3
+AIN3 -AIN2*
+AIN3
4
+AIN4
+AIN4 -AIN5
+AIN4
5
+AIN5
+AIN5 -AIN4*
+AIN5
6
+AIN6
+AIN6 -AIN7*
+AIN6
7
+AIN7
+AIN7 -AIN6*
+AIN7*
1 Not accessible on RCM3700 Prototyping Board.

gaincode is the gain code of 0 to 7
Gain Code Multiplier Voltage Range1
(V)
0
x1
0–20
1
x2
0–10
2
x4
0–5
3
x5
0–4
4
x8
0–2.5
5
x10
0–2
6
x16
0–1.25
7
x20
0–1
1 Applies to RCM3700 Prototyping Board.

Return Value
A value corresponding to the voltage on the analog input channel:

0–2047 for 11-bit A/D conversions (signed 12th bit)
ADOVERFLOW (defined macro = -4096) if overflow or out of range
-4095 if conversion is incomplete or busy-bit timeout

See Also

int anaInCalib(int channel, int opmode, int gaincode, int value1, float volts1, int value2, float volts2);


Calibrates the response of the desired A/D converter channel as a linear function using the two conversion points provided. Four values are calculated and placed into global tables to be later stored into simulated EEPROM using the function anaInEEWr(). Each channel will have a linear constant and a voltage offset.
Parameters
channel is the analog input channel number (0 to 7) corresponding to ADC_IN0 to ADC_IN7
opmode is the mode of operation:

SINGLE—single-ended input

DIFF—differential input

mAMP—milliamp input

channel SINGLE DIFF mAMP
0
+AIN0
+AIN0 -AIN1
+AIN01
1
+AIN1
+AIN1 -AIN0*
+AIN1*
2
+AIN2
+AIN2 -AIN3
+AIN2*
3
+AIN3
+AIN3 -AIN2*
+AIN3
4
+AIN4
+AIN4 -AIN5
+AIN4
5
+AIN5
+AIN5 -AIN4*
+AIN5
6
+AIN6
+AIN6 -AIN7*
+AIN6
7
+AIN7
+AIN7 -AIN6*
+AIN7*
1 Not accessible on RCM3700 Prototyping Board.

gaincode is the gain code of 0 to 7
Gain Code Multiplier Voltage Range1
(V)
0
x1
0–20
1
x2
0–10
2
x4
0–5
3
x5
0–4
4
x8
0–2.5
5
x10
0–2
6
x16
0–1.25
7
x20
0–1
1 Applies to RCM3700 Prototyping Board.

value1 is the first A/D converter channel value (0–2047)
volts1 is the voltage or current corresponding to the first A/D converter channel value (0 to +20 V or 4 to 20 mA)
value2 is the second A/D converter channel value (0–2047)
volts2 is the voltage or current corresponding to the first A/D converter channel value (0 to +20 V or 4 to 20 mA)
RETURN VALUE
0 if successful.
-1 if not able to make calibration constants.
SEE ALSO

float anaInVolts(unsigned int channel, unsigned int gaincode);


Reads the state of a single-ended analog input channel and uses the calibration constants previously set using anaInCalib to convert it to volts.
Parameters
channel is the channel number (0–7)
Channel Code Single-Ended Input Lines1 Voltage Range2
(V)
0
+AIN0
0–20
1
+AIN1
0–20
2
+AIN2
0–20
3
+AIN3
0–20
4
+AIN4
0–20
5
+AIN5
0–20
6
+AIN6
0–20
7
+AIN7
0–23
1 Negative input is ground.
2 Applies to RCM3700 Prototyping Board.
3 Used for thermistor in sample program.

gaincode is the gain code of 0 to 7
Gain Code Multiplier Voltage Range1
(V)
0
x1
0–20
1
x2
0–10
2
x4
0–5
3
x5
0–4
4
x8
0–2.5
5
x10
0–2
6
x16
0–1.25
7
x20
0–1
1 Applies to RCM3700 Prototyping Board.
Return Value
A voltage value corresponding to the voltage on the analog input channel.
ADOVERFLOW (defined macro = -4096) if overflow or out of range.
See Also

float anaInDiff(unsigned int channel, unsigned int gaincode);


Reads the state of differential analog input channels and uses the calibration constants previously set using anaInCalib to convert it to volts.
Parameters
channel is the analog input channel number (0 to 7) corresponding to ADC_IN0 to ADC_IN7
channel DIFF Voltage Range
(V)
0
+AIN0 -AIN1
-20 to +201
1
+AIN1 -AIN0
—
2
+AIN2 -AIN3
-20 to +20*
3
+AIN3 -AIN2
—
4
+AIN4 -AIN5
-20 to +20*
5
+AIN5 -AIN4
—
6
+AIN6 -AIN7
—
7
+AIN7 -AIN6
—
1 Applies to RCM3700 Prototyping Board.

gaincode is the gain code of 0 to 7
Gain Code Multiplier Voltage Range1
(V)
0
x1
0–20
1
x2
0–10
2
x4
0–5
3
x5
0–4
4
x8
0–2.5
5
x10
0–2
6
x16
0–1.25
7
x20
0–1
1 Applies to RCM3700 Prototyping Board.
Return Value
A voltage value corresponding to the voltage on the analog input channel.
ADOVERFLOW (defined macro = -4096) if overflow or out of range.
See Also

float anaInmAmps(unsigned int channel);


Reads the state of an analog input channel and uses the calibration constants previously set using anaInCalib to convert it to current.
Parameters
channel is the channel number (0–7)
Channel Code 4–20 mA
Input Lines1
0
+AIN0
1
+AIN1
2
+AIN2
3
+AIN32
4
+AIN4*
5
+AIN5*
6
+AIN6*
7
+AIN7
1 Negative input is ground.
2 Applies to RCM3700 Prototyping Board.

RETURN VALUE
A current value between 4.00 and 20.00 mA corresponding to the current on the analog input channel.
ADOVERFLOW (defined macro = -4096) if overflow or out of range.
SEE ALSO

root int anaInEERd(unsigned int channel, unsigned int opmode, unsigned int gaincode);


Reads the calibration constants, gain, and offset for an input based on their designated position in the simulated EEPROM area of the flash memory, and places them into global tables for analog inputs. The constants are stored in the top 2K of the reserved user block memory area 0x1C00–0x1FFF. Depending on the flash size, the following macros can be used to identify the starting address for these locations.

ADC_CALIB_ADDRS, address start of single-ended analog input channels

ADC_CALIB_ADDRD, address start of differential analog input channels

ADC_CALIB_ADDRM, address start of milliamp analog input channels

NOTE This function cannot be run in RAM.

PARAMETER
channel is the analog input channel number (0 to 7) corresponding to ADC_IN0 to ADC_IN7
opmode is the mode of operation:

SINGLE—single-ended input line

DIFF—differential input line

mAMP—milliamp input line

channel SINGLE DIFF mAMP
0
+AIN0
+AIN0 -AIN1
+AIN01
1
+AIN1
+AIN1 -AIN0*
+AIN1*
2
+AIN2
+AIN2 -AIN3
+AIN2*
3
+AIN3
+AIN3 -AIN2*
+AIN3
4
+AIN4
+AIN4 -AIN5
+AIN4
5
+AIN5
+AIN5 -AIN4*
+AIN5
6
+AIN6
+AIN6 -AIN7*
+AIN6
7
+AIN7
+AIN7 -AIN6*
+AIN7*
ALLCHAN
read all channels for selected opmode
1 Not accessible on RCM3700 Prototyping Board.

gaincode is the gain code of 0 to 7. The gaincode parameter is ignored when channel is ALLCHAN.
Gain Code Voltage Range1
(V)
0
0–20
1
0–10
2
0–5
3
0–4
4
0–2.5
5
0–2
6
0–1.25
7
0–1
1 Applies to RCM3700 Prototyping Board.
RETURN VALUE
0 if successful.
-1 if address is invalid or out of range.
-2 if there is no valid ID block.
SEE ALSO

int anaInEEWr(unsigned int channel, int opmode unsigned int gaincode);


Writes the calibration constants, gain, and offset for an input based from global tables to designated positions in the simulated EEPROM area of the flash memory. The constants are stored in the top 2K of the reserved user block memory area 0x1C00–0x1FFF. Depending on the flash size, the following macros can be used to identify the starting address for these locations.

ADC_CALIB_ADDRS, address start of single-ended analog input channels

ADC_CALIB_ADDRD, address start of differential analog input channels

ADC_CALIB_ADDRM, address start of milliamp analog input channels

NOTE This function cannot be run in RAM.

PARAMETER
channel is the analog input channel number (0 to 7) corresponding to ADC_IN0–ADC_IN7
opmode is the mode of operation:

SINGLE—single-ended input line

DIFF—differential input line

mAMP—milliamp input line

channel SINGLE DIFF mAMP
0
+AIN0
+AIN0 -AIN1
+AIN01
1
+AIN1
+AIN1 -AIN0*
+AIN1*
2
+AIN2
+AIN2 -AIN3
+AIN2*
3
+AIN3
+AIN3 -AIN2*
+AIN3
4
+AIN4
+AIN4 -AIN5
+AIN4
5
+AIN5
+AIN5 -AIN4*
+AIN5
6
+AIN6
+AIN6 -AIN7*
+AIN6
7
+AIN7
+AIN7 -AIN6*
+AIN7*
ALLCHAN
read all channels for selected opmode
1 Not accessible on RCM3700 Prototyping Board.

gaincode is the gain code of 0 to 7. The gaincode parameter is ignored when channel is ALLCHAN.
Gain Code Voltage Range1
(V)
0
0–20
1
0–10
2
0–5
3
0–4
4
0–2.5
5
0–2
6
0–1.25
7
0–1
1 Applies to RCM3700 Prototyping Board.
RETURN VALUE
0 if successful
-1 if address is invalid or out of range.
-2 if there is no valid ID block.
-3 if there is an error writing to flash memory.
SEE ALSO

void digConfig(char statemask);


Configures channels PIO0 to PIO3 on the A/D converter to allow them to be used as digital I/O via header JP4 on the RCM3700 Prototyping Board.
Remember to execute the brdInit function before calling this function to prevent a runtime error.
Parameter
statemask is a bitwise mask representing JP4 channels 1 to 4. Use logic 0 for inputs and logic 1 for outputs in these bit positions:

bits 7–5—0

bit 4—JP4:4

bit 3—JP4:3

bit 2—JP4:2

bit 1—JP4:1

bit 0—0

RETURN VALUE
None.
SEE ALSO

void digOut(int channel, int state);


Writes a state to a digital output channel on header JP4 of the RCM3700 Prototyping Board. The PIO0 to PIO3 channels on the A/D converter chip are accessed via header JP4 on the RCM3700 Prototyping Board.
A runtime error will occur if the brdInit function was not executed before calling this function or if the channel is out of range.
ParameterS
channel is channel 1 to 4 for JP4:1 to JP4:4
state is a logic state of 0 or 1
RETURN VALUE
None.
SEE ALSO

int digIn(int channel);


Reads the state of a digital input channel on header JP4 of the RCM3700 Prototyping Board. The PIO0 to PIO3 channels on the A/D converter chip are accessed via header JP4 on the RCM3700 Prototyping Board.
A runtime error will occur if the brdInit function was not executed before calling this function or if the channel is out of range.
ParameterS
channel is channel 1 to 4 for JP4:1 to JP4:4
state is a logic state of 0 or 1
RETURN VALUE
The logic state of the input (0 or 1).
SEE ALSO

5.2.3 Digital I/O

The RCM3700 was designed to interface with other systems, and so there are no drivers written specifically for the 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

to set all the Port E bits as inputs, or use

to set all the Port E bits as outputs.

When using the auxiliary I/O bus on the Rabbit