DOS platform (using Watcom C cross compiler) More...

Files
file	platform_config.h
	This file is automatically included by xbee/platform.h.

file	xbee_platform_dos.c
	Platform-specific functions for use by the XBee Driver on DOS target.

file	xbee_serial_dos.c
	Serial Interface for XBee Module (DOS Platform)

Data Structures
struct	xbee_serial_t

Macros
#define	PACKED_STRUCT _Packed struct

#define	XBEE_PACKED(name, decl) PACKED_STRUCT name decl

#define	_f_memcpy memcpy

#define	_f_memset memset

#define	__FUNCTION__ ""

#define	LITTLE_ENDIAN 1234

#define	BIG_ENDIAN 4321

#define	BYTE_ORDER LITTLE_ENDIAN

#define	FAR

#define	INTERRUPT_ENABLE _enable()

#define	INTERRUPT_DISABLE _disable()

#define	ZCL_TIME_EPOCH_DELTA ZCL_TIME_EPOCH_DELTA_1970

#define	XBEE_MS_TIMER_RESOLUTION (1000 / CLOCKS_PER_SEC)

#define	WPAN_MAX_CONVERSATIONS 6

#define	WPAN_CONVERSATION_TIMEOUT 15

#define	gotoxy00(x, y) gotoxy((x)+1, (y)+1)

#define	XBEE_READLINE_STATE_INIT 0

#define	XBEE_READLINE_STATE_START_LINE 1

#define	XBEE_READLINE_STATE_CONTINUE_LINE 2

#define	UART_RBR 0
	Receive Buffer DLAB = 0, read.

#define	UART_THR 0
	Transmitter Holding DLAB = 0, write.

#define	UART_DLL 0
	Divisor Latch LSB DLAB = 1.

#define	UART_IER 1
	Interrupt Enable DLAB = 0.

#define	UART_DLM 1
	Divisor Latch MSB DLAB = 1.

#define	UART_IIR 2
	Interrupt Identification read.

#define	UART_FCR 2
	FIFO Control write.

#define	UART_LCR 3
	Line Control.

#define	UART_MCR 4
	Modem Control.

#define	UART_LSR 5
	Line Status read.

#define	UART_MSR 6
	Modem Status read.

#define	UART_SCR 7
	Scratch.

#define	IER_NONE 0

#define	IER_RX_DATA (1<<0)

#define	IER_TX_EMPTY (1<<1)

#define	IER_LSR_CHANGE (1<<2)

#define	IER_MSR_CHANGE (1<<3)

#define	IER_DEFAULT (IER_RX_DATA \| IER_TX_EMPTY \| IER_LSR_CHANGE)

#define	FCR_DISABLE_FIFOS (0<<0)

#define	FCR_ENABLE_FIFOS (1<<0)

#define	FCR_CLEAR_RX_FIFO (1<<1)

#define	FCR_CLEAR_TX_FIFO (1<<2)

#define	FCR_DMA_MODE_0 (0<<3)

#define	FCR_DMA_MODE_1 (1<<3)

#define	FCR_ENABLE_64BYTE (1<<5)

#define	FCR_INT_TRIGGER_1BYTE (0<<6)

#define	FCR_INT_TRIGGER_4BYTE (1<<6)

#define	FCR_INT_TRIGGER_8BYTE (2<<6)

#define	FCR_INT_TRIGGER_14BYTE (3<<6)

#define	FCR_DEFAULT (FCR_ENABLE_FIFOS \| FCR_DMA_MODE_0)

#define	LCR_5BIT (0<<0)

#define	LCR_6BIT (1<<0)

#define	LCR_7BIT (2<<0)

#define	LCR_8BIT (3<<0)

#define	LCR_1STOP (0<<2)

#define	LCR_2STOP (1<<2)

#define	LCR_PARITY_NONE (0<<3)

#define	LCR_PARITY_ODD (1<<3)

#define	LCR_PARITY_EVEN (3<<3)

#define	LCR_PARITY_MARK (5<<3)

#define	LCR_PARITY_SPACE (7<<3)

#define	LCR_BREAK_ENABLE (1<<6)

#define	LCR_DIVISOR_LATCH (1<<7)

#define	LCR_DEFAULT (LCR_8BIT \| LCR_1STOP \| LCR_PARITY_NONE)

#define	MCR_NONE 0

#define	MCR_DTR (1<<0)

#define	MCR_RTS (1<<1)

#define	MCR_OUT1 (1<<2)

#define	MCR_OUT2 (1<<3)

#define	MCR_LOOPBACK (1<<4)

#define	MCR_AUTOFLOW (1<<5)

#define	MCR_DEFAULT (MCR_DTR \| MCR_RTS \| MCR_OUT2)

#define	MSR_CTS_CHANGED (1<<0)

#define	MSR_DSR_CHANGED (1<<1)

#define	MSR_RI_EDGE (1<<2)

#define	MSR_CD_CHANGED (1<<3)

#define	MSR_CTS (1<<4)

#define	MSR_DSR (1<<5)

#define	MSR_RI (1<<6)

#define	MSR_CD (1<<7)

#define	XBEE_SER_CHECK(ptr)

#define	CBUF_SIZE 255

Typedefs
typedef unsigned short	uint_fast8_t

typedef signed short	int_fast8_t

Functions
void	gotoxy_ansi (int col, int row)

void	clrscr_ansi (void)

uint32_t	xbee_seconds_timer ()
	Platform-specific function to return the number of elapsed seconds. More...

uint32_t	xbee_millisecond_timer ()
	Platform-specific function to return the number of elapsed milliseconds. More...

int	xbee_readline (char *buffer, int length)
	This function is a non-blocking version of gets(), used to read a line of input from the user. More...

void __interrupt __far	xbee_ser_isr ()

int	xbee_ser_invalid (xbee_serial_t *serial)
	Helper function used by other xbee_serial functions to validate the serial parameter. More...

const char *	xbee_ser_portname (xbee_serial_t *serial)
	Returns a human-readable string describing the serial port. More...

int	xbee_ser_write (xbee_serial_t serial, const void FAR buffer, int length)
	Transmits length bytes from buffer to the XBee serial port serial. More...

int	xbee_ser_read (xbee_serial_t serial, void FAR buffer, int bufsize)
	Reads up to bufsize bytes from XBee serial port serial and into buffer. More...

int	xbee_ser_putchar (xbee_serial_t *serial, uint8_t ch)
	Transmits a single character, ch, to the XBee serial port serial. More...

int	xbee_ser_getchar (xbee_serial_t *serial)
	Reads a single character from the XBee serial port serial. More...

int	xbee_ser_tx_free (xbee_serial_t *serial)
	Returns the number of bytes of unused space in the serial transmit buffer for XBee serial port serial. More...

int	xbee_ser_tx_used (xbee_serial_t *serial)
	Returns the number of queued bytes in the serial transmit buffer for XBee serial port serial. More...

int	xbee_ser_tx_flush (xbee_serial_t *serial)
	Flushes (i.e., deletes and does not transmit) characters in the serial transmit buffer for XBee serial port serial. More...

int	xbee_ser_rx_free (xbee_serial_t *serial)
	Returns the number of bytes of unused space in the serial receive buffer for XBee serial port serial. More...

int	xbee_ser_rx_used (xbee_serial_t *serial)
	Returns the number of queued bytes in the serial receive buffer for XBee serial port serial. More...

int	xbee_ser_rx_flush (xbee_serial_t *serial)
	Deletes all characters in the serial receive buffer for XBee serial port serial. More...

int	xbee_ser_baudrate (xbee_serial_t *serial, uint32_t baudrate)
	Change the baud rate of XBee serial port serial to baudrate bits/second. More...

int	xbee_ser_open (xbee_serial_t *serial, uint32_t baudrate)
	Opens the serial port connected to XBee serial port serial at baudrate bits/second. More...

int	xbee_ser_close (xbee_serial_t *serial)
	Close the serial port attached to XBee serial port serial. More...

int	xbee_ser_break (xbee_serial_t *serial, int enabled)
	Disable the serial transmit pin and pull it low to send a break to the XBee serial port. More...

int	xbee_ser_flowcontrol (xbee_serial_t *serial, int enabled)
	Enable or disable hardware flow control (CTS/RTS) on the serial port for XBee serial port serial. More...

int	xbee_ser_set_rts (xbee_serial_t *serial, int asserted)
	Disable hardware flow control and manually set the RTS (ready to send) pin on the XBee device's serial port. More...

int	xbee_ser_get_cts (xbee_serial_t *serial)
	Read the status of the /CTS (clear to send) pin on the serial port connected to XBee serial port serial. More...

platform_stdint
Types typically defined in <stdint.h>, define manually if stdint.h is not available on this platform.
typedef signed char	int8_t
	8-bit signed integer

typedef unsigned char	uint8_t
	8-bit unsigned integer More...

typedef short	int16_t
	16-bit signed integer

typedef unsigned short	uint16_t
	16-bit unsigned integer

typedef long	int32_t
	32-bit signed integer

typedef unsigned long	uint32_t
	32-bit unsigned integer

typedef int	bool_t
	Variable that can hold 0 or 1, may be an `int` for speed purporses or `uint8_t` for size optimization.

Detailed Description

DOS platform (using Watcom C cross compiler)

Typedef Documentation

uint8_t

8-bit unsigned integer

Calculate the checksum for an XBee frame.

This function actually subtracts bytes from 0xFF, in order to determine the proper checksum byte so all bytes added together result in 0x00.

Frame checksums start with the frame type (first byte after frame length).

If calculating a checksum for an outgoing packet, sum all of the bytes using this function, and send the low byte of the result.

If verifying a received packet, summing all of the bytes after the length, including the packet's checksum byte, should result in 0x00.

Should only be used internally by this library.

Parameters

[in]	bytes	Buffer of bytes to add to sum, assumed non-NULL.
[in]	length	Number of bytes to add.
[in]	initial	Starting checksum value. Use 0xFF to start or the result of the previous call if summing multiple blocks of data.

Returns: Value from 0x00 to 0xFF that, when added to all bytes previously checksummed, results in a low byte of 0x00.

Function Documentation

uint32_t xbee_millisecond_timer ( void )

Platform-specific function to return the number of elapsed milliseconds.

OK for this counter to rollover. Used for timing and should have a resolution of at least 60ms.

Rabbit has 1ms resolution.
HCS08 has 4ms resolution.
DOS has 18 ticks/second (55.55ms resolution)

(Function name wrapped in parentheses so platforms can use a macro function of the same name.)

Returns: Number of elapsed milliseconds.

See also: XBEE_MS_TIMER_RESOLUTION

int xbee_readline	(	char *	buffer,
		int	length
	)

This function is a non-blocking version of gets(), used to read a line of input from the user.

It waits for a string from stdin terminated by a return. It should be called repeatedly, until it returns a value other than -EAGAIN. The input string, stored in buffer is null-terminated without the return.

The user should make sure only one process calls this function at a time.

Parameters

[in,out]	buffer	buffer to store input from user
[in]	length	size of buffer

Return values

>=0	User ended the input with a newline, return value is number of bytes written.
-EAGAIN	User has not completed a line.
-EINVAL	NULL buffer or length is less than 1.
-ENODATA	User entered CTRL-D to end input.

References EAGAIN, and EINVAL.

uint32_t xbee_seconds_timer ( void )

Platform-specific function to return the number of elapsed seconds.

On some platforms, this is the equivalent of an "uptime".

On other platforms, it may reflect the value of the RTC, which might not be synchronized with a time server and might include leap seconds.

Regardless, it should consistently report elapsed time and not jump on clock synchronization.

In addition to determining timeouts, the ZCL Time Cluster makes use of it to report current time.

(Function name wrapped in parentheses so platforms can use a macro function of the same name.)

Returns: Number of elapsed seconds.

int xbee_ser_baudrate	(	xbee_serial_t *	serial,
		uint32_t	baudrate
	)

Change the baud rate of XBee serial port serial to baudrate bits/second.

Parameters

[in]	serial	XBee serial port
[in]	baudrate	Bits per second of serial data transfer speed.

Return values

0	Opened serial port within 5% of requested baudrate.
-EINVAL	serial is not a valid XBee serial port.
-EIO	Can't open serial port within 5% of requested baudrate.

See also: xbee_ser_open(), xbee_ser_close(), xbee_ser_break()

References EINVAL, PRIu32, UART_DLL, UART_DLM, and UART_LCR.

Referenced by xbee_ser_open().

int xbee_ser_break	(	xbee_serial_t *	serial,
		int	enabled
	)

Disable the serial transmit pin and pull it low to send a break to the XBee serial port.

Parameters

[in]	serial	XBee serial port
[in]	enabled	Set to 1 to start the break or 0 to end the break (and resume transmitting).

Return values

0	Success
-EINVAL	serial is not a valid XBee serial port.

See also: xbee_ser_open(), xbee_ser_close()

References UART_LCR.

int xbee_ser_close ( xbee_serial_t * serial )

Close the serial port attached to XBee serial port serial.

Parameters

[in] serial XBee serial port

Return values

0	closed serial port
-EINVAL	serial is not a valid XBee serial port.

See also: xbee_ser_open(), xbee_ser_baudrate(), xbee_ser_break()

References UART_IER, and UART_MCR.

Referenced by xbee_ser_open().

int xbee_ser_flowcontrol	(	xbee_serial_t *	serial,
		int	enabled
	)

Enable or disable hardware flow control (CTS/RTS) on the serial port for XBee serial port serial.

Parameters

[in]	serial	XBee serial port
[in]	enabled	Set to 0 to disable flow control or non-zero to enable flow control.

Return values

0	Success
-EINVAL	serial is not a valid XBee serial port.

See also: xbee_ser_set_rts(), xbee_ser_get_cts()

References UART_MCR.

int xbee_ser_get_cts ( xbee_serial_t * serial )

Read the status of the /CTS (clear to send) pin on the serial port connected to XBee serial port serial.

Note that this function doesn't return the value of the pin – it returns whether it's asserted (i.e., clear to send to the XBee serial port) or not.

Parameters

[in] serial XBee serial port

Return values

1	it's clear to send
0	it's not clear to send
-EINVAL	serial is not a valid XBee serial port.

See also: xbee_ser_flowcontrol(), xbee_ser_set_rts()

References UART_MSR.

int xbee_ser_getchar ( xbee_serial_t * serial )

Reads a single character from the XBee serial port serial.

Parameters

[in] serial XBee serial port

Return values

0-255	character read from XBee serial port
-ENODATA	There aren't any characters in the read buffer.
-EINVAL	serial is not a valid XBee serial port.

See also: xbee_ser_read(), xbee_ser_write(), xbee_ser_getchar()

References ENODATA, and xbee_ser_read().

int xbee_ser_invalid ( xbee_serial_t * serial )

Helper function used by other xbee_serial functions to validate the serial parameter.

Confirms that it is non-NULL and is set to a valid port.

Parameters

[in] serial XBee serial port

Return values

1	serial is not a valid XBee serial port
0	serial is a valid XBee serial port

int xbee_ser_open	(	xbee_serial_t *	serial,
		uint32_t	baudrate
	)

Opens the serial port connected to XBee serial port serial at baudrate bits/second.

Parameters

[in]	serial	XBee serial port
[in]	baudrate	Bits per second of serial data transfer speed.

Return values

0	Opened serial port within 5% of requested baudrate.
-EINVAL	serial is not a valid XBee serial port.
-EIO	Can't open serial port within 5% of requested baudrate.

See also: xbee_ser_baudrate(), xbee_ser_close(), xbee_ser_break()

References EINVAL, PRIu32, UART_FCR, UART_IER, UART_LCR, UART_LSR, UART_MCR, UART_MSR, UART_RBR, xbee_cbuf_init(), xbee_ser_baudrate(), and xbee_ser_close().

const char* xbee_ser_portname ( xbee_serial_t * serial )

Returns a human-readable string describing the serial port.

For example, on a Windows machine this will be "COM1" or "COM999". On a Rabbit, it will be a single letter, "A" through "F". On Freescale HCS08, it will be something like "SCI1" or "SCI2". On POSIX, the name of the device (e.g., "/dev/ttyS0")

Returns "(invalid)" if serial is invalid or not configured.

Parameters

[in] serial port

Returns: null-terminated string describing the serial port

int xbee_ser_putchar	(	xbee_serial_t *	serial,
		uint8_t	ch
	)

Transmits a single character, ch, to the XBee serial port serial.

Parameters

[in]	serial	XBee serial port
[in]	ch	character to send

Return values

0	Successfully sent (queued) character.
-ENOSPC	The write buffer is full and the character wasn't sent.
-EINVAL	serial is not a valid XBee serial port.

See also: xbee_ser_read(), xbee_ser_write(), xbee_ser_getchar()

References ENOSPC, and xbee_ser_write().

int xbee_ser_read	(	xbee_serial_t *	serial,
		void FAR *	buffer,
		int	bufsize
	)

Reads up to bufsize bytes from XBee serial port serial and into buffer.

If there is no data available when the function is called, it will return immediately.

Parameters

[in]	serial	XBee serial port
[out]	buffer	buffer to hold bytes read from XBee serial port
[in]	bufsize	maximum number of bytes to read

Return values

>=0	The number of bytes read from XBee serial port.
-EINVAL	serial is not a valid XBee serial port.
-EIO	I/O error attempting to write to serial port.

See also: xbee_ser_write(), xbee_ser_putchar(), xbee_ser_getchar()

References EINVAL, hex_dump(), HEX_DUMP_FLAG_TAB, xbee_cbuf_get(), and xbee_cbuf_used().

Referenced by xbee_ser_getchar().

int xbee_ser_rx_flush ( xbee_serial_t * serial )

Deletes all characters in the serial receive buffer for XBee serial port serial.

Parameters

[in] serial XBee serial port

Return values

0	success
-EINVAL	serial is not a valid XBee serial port.

See also: xbee_ser_tx_free(), xbee_ser_tx_used(), xbee_ser_tx_flush(), xbee_ser_rx_free(), xbee_ser_rx_used()

References INTERRUPT_DISABLE, INTERRUPT_ENABLE, UART_FCR, UART_LSR, UART_RBR, and xbee_cbuf_flush().

int xbee_ser_rx_free ( xbee_serial_t * serial )

Returns the number of bytes of unused space in the serial receive buffer for XBee serial port serial.

Parameters

[in] serial XBee serial port

Return values

INT_MAX	The buffer size is unlimited (or unknown).
>=0	The number of bytes it would take to fill the XBee serial port's serial receive buffer.
-EINVAL	serial is not a valid XBee serial port.

See also: xbee_ser_tx_free(), xbee_ser_tx_used(), xbee_ser_tx_flush(), xbee_ser_rx_used(), xbee_ser_rx_flush()

References xbee_cbuf_free().

int xbee_ser_rx_used ( xbee_serial_t * serial )

Returns the number of queued bytes in the serial receive buffer for XBee serial port serial.

Parameters

[in] serial XBee serial port

Return values

>=0	The number of bytes queued in the XBee serial port's serial transmit buffer.
-EINVAL	serial is not a valid XBee serial port.

See also: xbee_ser_tx_free(), xbee_ser_tx_used(), xbee_ser_tx_flush(), xbee_ser_rx_free(), xbee_ser_rx_flush()

Note: Unlike xbee_ser_tx_used(), this function MUST return the number of bytes available. Some layers of the library wait until enough bytes are ready before continuing.

We may expand on or replace this API. On some platforms (like Win32) we have to do some of our own buffering in order to peek at data in the serial receive buffer. Most of the driver only requires a check to see if some number of bytes are available or not. Consider changing the API to something like:

1 int xbee_ser_rx_avail( xbee_serial_t *serial, uint8_t count)

returns TRUE if count bytes are available, FALSE otherwise.

References xbee_cbuf_used().

int xbee_ser_set_rts	(	xbee_serial_t *	serial,
		int	asserted
	)

Disable hardware flow control and manually set the RTS (ready to send) pin on the XBee device's serial port.

Typically used to enter the XBee device's boot loader and initiate a firmware update.

Parameters

[in]	serial	XBee serial port
[in]	asserted	Set to 1 to assert RTS (ok for XBee to send to us) or 0 to deassert RTS (tell XBee not to send to us).

Return values

0	Success
-EINVAL	serial is not a valid XBee serial port.

See also: xbee_ser_flowcontrol(), xbee_ser_get_cts()

References UART_MCR.

int xbee_ser_tx_flush ( xbee_serial_t * serial )

Flushes (i.e., deletes and does not transmit) characters in the serial transmit buffer for XBee serial port serial.

Parameters

[in] serial XBee serial port

Return values

0	success
-EINVAL	serial is not a valid XBee serial port.

See also: xbee_ser_rx_free(), xbee_ser_rx_used(), xbee_ser_rx_flush(), xbee_ser_tx_free(), xbee_ser_tx_used()

References INTERRUPT_DISABLE, INTERRUPT_ENABLE, UART_FCR, UART_IER, and xbee_cbuf_flush().

int xbee_ser_tx_free ( xbee_serial_t * serial )

Returns the number of bytes of unused space in the serial transmit buffer for XBee serial port serial.

Parameters

[in] serial XBee serial port

Return values

INT_MAX	The buffer size is unlimited (or unknown).
>=0	The number of bytes it would take to fill the XBee serial port's serial transmit buffer.
-EINVAL	serial is not a valid XBee serial port.

See also: xbee_ser_rx_free(), xbee_ser_rx_used(), xbee_ser_rx_flush(), xbee_ser_tx_used(), xbee_ser_tx_flush()

References xbee_cbuf_free().

int xbee_ser_tx_used ( xbee_serial_t * serial )

Returns the number of queued bytes in the serial transmit buffer for XBee serial port serial.

Parameters

[in] serial XBee serial port

Return values

0	The buffer size is unlimited (or space used is unknown).
>0	The number of bytes queued in the XBee serial port's serial transmit buffer.
-EINVAL	serial is not a valid XBee serial port.

See also: xbee_ser_rx_free(), xbee_ser_rx_used(), xbee_ser_rx_flush(), xbee_ser_tx_free(), xbee_ser_tx_flush()

References xbee_cbuf_used().

int xbee_ser_write	(	xbee_serial_t *	serial,
		const void FAR *	buffer,
		int	length
	)

Transmits length bytes from buffer to the XBee serial port serial.

Parameters

[in]	serial	XBee serial port
[in]	buffer	source of bytes to send
[in]	length	number of bytes to write

Return values

>=0	The number of bytes successfully written to XBee serial port.
-EINVAL	serial is not a valid XBee serial port.
-EIO	I/O error attempting to write to serial port.

See also: xbee_ser_read(), xbee_ser_putchar(), xbee_ser_getchar()

References EINVAL, FAR, hex_dump(), HEX_DUMP_FLAG_TAB, INTERRUPT_DISABLE, INTERRUPT_ENABLE, UART_IER, UART_LSR, UART_THR, xbee_cbuf_free(), xbee_cbuf_getch(), and xbee_cbuf_put().

Referenced by xbee_ser_putchar().

Files

Data Structures

Macros

Typedefs

Functions

platform_stdint

Detailed Description

Typedef Documentation

Function Documentation