HAL: EFM32/Simplicity Studio

Files
file	xbee_platform_efm32.c
	Platform header for efm32.
file	xbee_platform_efm32.c
	Platform header for efm32.
file	xbee_platform_efm32.c
	Platform header for efm32.
file	xbee_serial_efm32.c
	Serial Interface for XBee Module (EFM32 Microcontroller)

Data Structures
struct	xbee_serial_t

Macros
#define	_f_memcpy   memcpy
#define	_f_memset   memset
#define	LITTLE_ENDIAN   4321
#define	BIG_ENDIAN   1234
#define	BYTE_ORDER   LITTLE_ENDIAN
#define	PACKED_STRUCT   struct __attribute__ ((__packed__))
#define	XBEE_PACKED(name, decl)   PACKED_STRUCT name decl
#define	XBEE_MS_TIMER_RESOLUTION   1
#define	ZCL_TIME_EPOCH_DELTA   0
#define	XBEE_PLATFORM_INIT()   xbee_platform_init()
#define	RX_BUFF_SIZE   255 /* Receive buffer = 2^n -1 for some integer n) */
#define	TX_BUFF_SIZE   RX_BUFF_SIZE /* Transmit buffer (same as Rx buffer) */
#define	USART_NUMBER   0 /* The USART peripheral number you are using */
#define	XBEE_TXPORT   gpioPortE /* USART transmission port */
#define	XBEE_TXPIN   10 /* USART transmission pin */
#define	XBEE_RXPORT   gpioPortE /* USART reception port */
#define	XBEE_RXPIN   11 /* USART reception pin */
#define	XBEE_RTSPORT   gpioPortE /* USART RTS flow control port */
#define	XBEE_RTSPIN   13 /* USART RTS flow control pin */
#define	XBEE_CTSPORT   gpioPortB /* USART CTS flow control port */
#define	XBEE_CTSPIN   11 /* USART CTS flow control pin */
#define	TX_LOC   0
#define	RX_LOC   0
#define	CTS_LOC   5
#define	BUFFER_UPPER_BOUND   4
#define	BUFFER_LOWER_BOUND   RX_BUFF_SIZE/3
#define	XBEE_RX_IRQn   CONCAT3(USART, USART_NUMBER, _RX_IRQn) /* IRQRX number */
#define	XBEE_TX_IRQn   CONCAT3(USART, USART_NUMBER, _TX_IRQn) /* IRQTX number */
#define	XBEE_RX_IRQ_NAME   CONCAT3(USART, USART_NUMBER, _RX_IRQHandler) /* USART IRQ Handler */
#define	XBEE_TX_IRQ_NAME   CONCAT3(USART, USART_NUMBER, _TX_IRQHandler) /* USART IRQ Handler */
#define	XBEE_USART   CONCAT(USART, USART_NUMBER) /* USART instance */
#define	XBEE_CLK   CONCAT3(cmuClock, _USART, USART_NUMBER) /* HFPER Clock */
#define	XBEE_ROUTE_LOC_TX   CONCAT(USART_ROUTELOC0_TXLOC_LOC,TX_LOC) /* HFPER Clock */
#define	XBEE_ROUTE_LOC_RX   CONCAT(USART_ROUTELOC0_RXLOC_LOC,TX_LOC)
#define	XBEE_ROUTE_LOC_CTS   CONCAT(USART_ROUTELOC1_CTSLOC_LOC, CTS_LOC)
#define	XBEE_USART_STRING   TOSTRINGMACRO(CONCAT(USART_, USART_NUMBER)) /* String version of USART_# */
#define	TOSTRINGMACRO(s)   TOSTRINGMACRO_(s)
#define	TOSTRINGMACRO_(s)   #s
#define	CONCAT_(A, B)   A ## B
#define	CONCAT(A, B)   CONCAT_(A, B)
#define	CONCAT3_(A, B, C)   A ## B ## C
#define	CONCAT3(A, B, C)   CONCAT3_(A, B, C)

Typedefs
typedef uint8_t	bool_t

Functions
int	xbee_platform_init (void)
void	SysTick_Handler (void)
	SysTick_Handler Interrupt Service Routine for system tick counters.
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...
void	checkRxBufferUpper (void)
void	checkRxBufferLower (void)
void	routeSerial (void)
void	serialInit (xbee_serial_t *serial)
void	XBEE_RX_IRQ_NAME (void)
void	XBEE_TX_IRQ_NAME (void)
bool_t	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_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_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_close (xbee_serial_t *serial)
	Close the serial port attached to XBee serial port serial. More...
int	xbee_ser_break (xbee_serial_t *serial, bool_t 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, bool_t 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, bool_t 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...

Variables
USART_TypeDef *	usart = XBEE_USART

Detailed Description

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

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, EIO, and xbee_ser_invalid().

Referenced by xbee_ser_open().

int xbee_ser_break	(	xbee_serial_t *	serial,
		bool_t	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 EINVAL, and xbee_ser_invalid().

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 EINVAL, xbee_ser_invalid(), xbee_ser_rx_flush(), and xbee_ser_tx_flush().

int xbee_ser_flowcontrol	(	xbee_serial_t *	serial,
		bool_t	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 EINVAL, and xbee_ser_invalid().

Referenced by xbee_ser_set_rts().

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 EINVAL, and xbee_ser_invalid().

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 EINVAL, ENODATA, xbee_cbuf_getch(), and xbee_ser_invalid().

bool_t 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

Referenced by xbee_ser_baudrate(), xbee_ser_break(), xbee_ser_close(), xbee_ser_flowcontrol(), xbee_ser_get_cts(), xbee_ser_getchar(), xbee_ser_open(), xbee_ser_putchar(), xbee_ser_read(), xbee_ser_rx_flush(), xbee_ser_rx_free(), xbee_ser_rx_used(), xbee_ser_tx_flush(), xbee_ser_tx_free(), xbee_ser_tx_used(), and xbee_ser_write().

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, xbee_ser_baudrate(), and xbee_ser_invalid().

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 EINVAL, EIO, ENOSPC, xbee_cbuf_putch(), and xbee_ser_invalid().

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, EIO, xbee_cbuf_get(), and xbee_ser_invalid().

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 EINVAL, xbee_cbuf_flush(), and xbee_ser_invalid().

Referenced by xbee_ser_close().

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 EINVAL, xbee_cbuf_free(), and xbee_ser_invalid().

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:

int xbee_ser_rx_avail( xbee_serial_t *serial, uint8_t count)

returns TRUE if count bytes are available, FALSE otherwise.

References EINVAL, xbee_cbuf_used(), and xbee_ser_invalid().

int xbee_ser_set_rts	(	xbee_serial_t *	serial,
		bool_t	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 xbee_ser_flowcontrol().

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 EINVAL, xbee_cbuf_flush(), and xbee_ser_invalid().

Referenced by xbee_ser_close().

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 EINVAL, xbee_cbuf_free(), and xbee_ser_invalid().

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 EINVAL, xbee_cbuf_used(), and xbee_ser_invalid().

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, EIO, xbee_cbuf_put(), and xbee_ser_invalid().