Frames: Input Sample (0x92)

Code related to built-in I/Os on the XBee module (the ATIS command, 0x92 frames). More...

Files
file	io.h
file	xbee_io.c

Data Structures
struct	xbee_io_t
struct	xbee_frame_io_response_t
	< XBEE_FRAME_IO_RESPONSE (0x92) ATSH and ATSL of sender ATMY value of sender More...

Macros
#define	XBEE_IO_ANALOG_INVALID   INT16_C(-32768)
	Return code from analog I/O query functions if selected I/O is not valid.
#define	XBEE_IO_MIN_SAMPLE_PERIOD   50
	Minimum automatic I/O sample period in ms.
#define	_xbee_io_debug

Enumerations
enum	xbee_io_type {   XBEE_IO_TYPE_DISABLED = 0, XBEE_IO_TYPE_SPECIAL = 1, XBEE_IO_TYPE_ANALOG_INPUT = 2, XBEE_IO_TYPE_DIGITAL_INPUT = 3,   XBEE_IO_TYPE_DIGITAL_OUTPUT_LOW = 4, XBEE_IO_TYPE_DIGITAL_OUTPUT_HIGH = 5, XBEE_IO_TYPE_TXEN_ACTIVE_LOW = 6, XBEE_IO_TYPE_TXEN_ACTIVE_HIGH = 7,   XBEE_IO_TYPE_MASK = 0x0F, XBEE_IO_TYPE_CHANGE_DETECT = 0x10, XBEE_IO_TYPE_PULLUP = 0x20, XBEE_IO_TYPE_PULLDOWN = 0x40,   XBEE_IO_FORCE = 0x80, XBEE_IO_TYPE_DIGITAL_INPUT_PULLUP }
	Configuration type for XBee built-in I/Os. More...
enum	xbee_io_digital_output_state { XBEE_IO_SET_LOW = XBEE_IO_TYPE_DIGITAL_OUTPUT_LOW, XBEE_IO_SET_HIGH = XBEE_IO_TYPE_DIGITAL_OUTPUT_HIGH, XBEE_IO_FORCE_LOW = XBEE_IO_SET_LOW|XBEE_IO_FORCE, XBEE_IO_FORCE_HIGH = XBEE_IO_SET_HIGH|XBEE_IO_FORCE }
	Digital output state for XBee built-in I/Os configured as outputs. More...

Functions
int	xbee_io_response_parse (xbee_io_t FAR *parsed, const void FAR *source)
	Parse an I/O response and store it in an xbee_io_t structure. More...
void	xbee_io_response_dump (const xbee_io_t FAR *io)
	Debugging function used to dump an xbee_io_t structure to stdout. More...
int	xbee_io_get_digital_input (const xbee_io_t FAR *io, uint_fast8_t index)
	Return state of a digital input. More...
int	xbee_io_get_digital_output (const xbee_io_t FAR *io, uint_fast8_t index)
	Return state of a digital output. More...
int16_t	xbee_io_get_analog_input (const xbee_io_t FAR *io, uint_fast8_t index)
	Return reading of an analog input. More...
int	xbee_io_set_digital_output (xbee_dev_t *xbee, xbee_io_t FAR *io, uint_fast8_t index, enum xbee_io_digital_output_state state, const wpan_address_t FAR *address)
	Set state of a digital output. More...
int	xbee_io_configure (xbee_dev_t *xbee, xbee_io_t FAR *io, uint_fast8_t index, enum xbee_io_type type, const wpan_address_t FAR *address)
	Configure XBee digital and analog I/Os. More...
int	xbee_io_set_options (xbee_dev_t *xbee, xbee_io_t FAR *io, uint16_t sample_rate, uint16_t change_mask, const wpan_address_t FAR *address)
	Configure XBee automatic I/O sampling options. More...
int	xbee_io_query (xbee_dev_t *xbee, xbee_io_t FAR *io, const wpan_address_t FAR *address)
int	xbee_io_query_status (xbee_io_t FAR *io)
	Check the status of querying an XBee device, as initiated by xbee_io_query(). More...
char *	_xbee_mask_to_binary (char *buf, uint16_t mask, char *digits, int maxbit)
char *	_xbee_2masks_to_quaternary (char *buf, uint16_t mask_lo, uint16_t mask_hi, char *digits, int maxbit)
void	_xbee_io_query_handle_pr (const xbee_cmd_response_t FAR *response, const struct xbee_atcmd_reg_t FAR *reg, void FAR *base)
void	_xbee_io_query_handle_end (const xbee_cmd_response_t FAR *response, const struct xbee_atcmd_reg_t FAR *reg, void FAR *base)

Variables
const FAR xbee_at_cmd_t	xbee_io_cmd_by_index []
const FAR xbee_at_cmd_t	xbee_io_cmd_by_index [16]
const uint16_t	_xbee_pullup_atcmd_to_iomask [16]
	Read current configuration of XBee digital and analog I/Os. More...
const xbee_atcmd_reg_t	_xbee_io_query_regs []

XBee configurable I/O pin names. Bitmask applied to certain fields.
#define	XBEE_IO_AD0   0x0001
	AD0 (pin 20)
#define	XBEE_IO_DIO0   0x0001
	DIO0 (pin 20) - also commissioning button if so configured.
#define	XBEE_IO_AD1   0x0002
	AD1 (pin 19)
#define	XBEE_IO_DIO1   0x0002
	DIO1 (pin 19)
#define	XBEE_IO_AD2   0x0004
	AD2 (pin 18)
#define	XBEE_IO_DIO2   0x0004
	DIO2 (pin 18)
#define	XBEE_IO_AD3   0x0008
	AD3 (pin 17)
#define	XBEE_IO_DIO3   0x0008
	DIO3 (pin 17)
#define	XBEE_IO_DIO4   0x0010
	DIO4 (pin 11)
#define	XBEE_IO_DIO5   0x0020
	DIO5 (pin 15) - also ASSOC indicator if so configured.
#define	XBEE_IO_DIO6   0x0040
	DIO6 (pin 16) - also RTS flow control if so configured.
#define	XBEE_IO_DIO7   0x0080
	DIO7 (pin 12) - also CTS flow control if so configured.
#define	XBEE_IO_GPIO7   0x0080
#define	XBEE_IO_VCC_SENSE   0x80
	Supply voltage sense (in xbee_io_t.analog_enabled field)
#define	XBEE_IO_DIO10   0x0400
	DIO10 (pin 6) - also RSSI PWM if so configured.
#define	XBEE_IO_DIO11   0x0800
	DIO11 (pin 7)
#define	XBEE_IO_DIO12   0x1000
	DIO12 (pin 4) - also CD signal if so configured.

Detailed Description

Code related to built-in I/Os on the XBee module (the ATIS command, 0x92 frames).

Enumeration Type Documentation

enum xbee_io_digital_output_state

Digital output state for XBee built-in I/Os configured as outputs.

Enumerator
XBEE_IO_SET_LOW	Low (0V)
XBEE_IO_SET_HIGH	High (Vcc)

enum xbee_io_type

Configuration type for XBee built-in I/Os.

Follows encoding in ATD0 etc., but also add pullup state as bit encoding.

Enumerator
XBEE_IO_TYPE_DISABLED	Disabled.
XBEE_IO_TYPE_SPECIAL	Special function e.g. association indicator for DIO5
XBEE_IO_TYPE_ANALOG_INPUT	Analog input.
XBEE_IO_TYPE_DIGITAL_INPUT	Digital input.
XBEE_IO_TYPE_DIGITAL_OUTPUT_LOW	Digital output low.
XBEE_IO_TYPE_DIGITAL_OUTPUT_HIGH	Digital output high.
XBEE_IO_TYPE_TXEN_ACTIVE_LOW	RS485 transmit enable (act low)
XBEE_IO_TYPE_TXEN_ACTIVE_HIGH	RS485 transmit enable (act high)
XBEE_IO_TYPE_MASK	Mask for above settings.
XBEE_IO_TYPE_CHANGE_DETECT	OR in to the above to specify automatic sampling when edge detected (ATIC command).
XBEE_IO_TYPE_PULLUP	OR in to the above to specify pull-up resistor active (ATPR command).
XBEE_IO_TYPE_PULLDOWN	OR in to the above to specify pull-down resistor active (reserved for future hardware).
XBEE_IO_FORCE	OR in to the above to force transmit to the device (else only transmits if changed from last known state)

Function Documentation

int xbee_io_configure	(	xbee_dev_t *	xbee,
		xbee_io_t FAR *	io,
		uint_fast8_t	index,
		enum xbee_io_type	type,
		const wpan_address_t FAR *	address
	)

Configure XBee digital and analog I/Os.

This modifies the shadow state in the io parameter, as well as sending the appropriate configuration command to the target device. If the new state is the same as the shadow state, then the function returns without doing anything, unless XBEE_IO_FORCE is specified in the type parameter.

Parameters

[in,out]	xbee	local device through which to action the request
[in,out]	io	pointer to an xbee_io_t structure as set up by xbee_io_query(). Shadow state of I/O may be modified
[in]	index	digital or analog I/O number e.g. 0 for DIO0 or AD0.
[in]	type	type of I/O to configure. If the XBEE_IO_FORCE flag is ORed in, force a configuration update to the device. Otherwise, a configuration change will only be sent to the device if the shadow (i.e. last known) configuration is different.
[in]	address	NULL for local XBee, or destination IEEE (64-bit) or network (16 bit) address of a remote device.

Return values

0	Success
-EINVAL	Specified I/O index does not exist, or bad parameter.
-ENOSPC	the AT command table is full (increase the compile-time macro XBEE_CMD_REQUEST_TABLESIZE)
-EPERM	Specified I/O cannot be configured as requested because the hardware or firmware does not support it.
<0	Other negative value indicates problem transmitting the configuration request.

Todo:

: this is a relatively crude test. Need to look at hardware

References EINVAL, EPERM, FAR, xbee_cmd_create(), xbee_cmd_send(), xbee_cmd_set_param(), xbee_cmd_set_target(), XBEE_IO_FORCE, XBEE_IO_TYPE_ANALOG_INPUT, XBEE_IO_TYPE_DIGITAL_INPUT, XBEE_IO_TYPE_DIGITAL_OUTPUT_HIGH, XBEE_IO_TYPE_DIGITAL_OUTPUT_LOW, XBEE_IO_TYPE_MASK, XBEE_IO_TYPE_SPECIAL, and XBEE_IO_TYPE_TXEN_ACTIVE_HIGH.

Referenced by _sxa_io_process_response().

int16_t xbee_io_get_analog_input	(	const xbee_io_t FAR *	io,
		uint_fast8_t	index
	)

Return reading of an analog input.

Parameters

[in]	io	pointer to an xbee_io_t structure as set up by xbee_io_response_parse()
[in]	index	analog input number e.g. 0 for AD0, 2 for AD2, 7 for Vcc reading (where available)

Return values

0..32767	raw single-ended analog reading, normalized to the range 0..32767. Current hardware supports 10-bit ADCs, hence the 5 LSBs will be zero. Future hardware with higher resolution ADCs will add precision to the LSBs.
-16384..16383	raw differential analog reading, normalized to the range -16384..16383. This is reserved for future hardware.
XBEE_IO_ANALOG_INVALID	Output unknown because not configured as an analog input, or is a non-existent input index.

References FAR, and XBEE_IO_ANALOG_INVALID.

Referenced by _sxa_io_process_response().

int xbee_io_get_digital_input	(	const xbee_io_t FAR *	io,
		uint_fast8_t	index
	)

Return state of a digital input.

Parameters

[in]	io	pointer to an xbee_io_t structure as set up by xbee_io_response_parse()
[in]	index	digital input number e.g. 0 for DIO0, 12 for DIO12.

Return values

0	Input low
1	Input high
-EINVAL	Input unknown because not configured as a digital input, or is a non-existent input index.

References EINVAL.

Referenced by _sxa_io_process_response().

int xbee_io_get_digital_output	(	const xbee_io_t FAR *	io,
		uint_fast8_t	index
	)

Return state of a digital output.

This is a shadow state i.e. the last known state setting.

Parameters

[in]	io	pointer to an xbee_io_t structure as set up by xbee_io_query()
[in]	index	digital output number e.g. 0 for DIO0, 2 for DIO2.

Return values

0	Output low
1	Output high
-EINVAL	Output unknown because not configured as a digital output, or is a non-existent output index.

References EINVAL.

Referenced by _sxa_io_process_response().

int xbee_io_query_status

(

xbee_io_t FAR *

io

)

Check the status of querying an XBee device, as initiated by xbee_io_query().

Parameters

[in]

io

I/O query to check (pointer as passed to xbee_io_query()).

Return values

0	query completed
-EINVAL	io is NULL
-EBUSY	query underway
-ETIMEDOUT	query timed out
-EIO	halted, but query may not have completed (unexpected response)

References EINVAL, xbee_cmd_list_status(), and xbee_cmd_tick().

Referenced by _sxa_io_process_response().

void xbee_io_response_dump

(

const xbee_io_t FAR *

io

)

Debugging function used to dump an xbee_io_t structure to stdout.

Parameters

[in]

io

pointer to an xbee_io_t structure as set up by xbee_io_response_parse()

References _TABLE_ENTRIES.

Referenced by _sxa_io_process_response().

int xbee_io_response_parse	(	xbee_io_t FAR *	parsed,
		const void FAR *	source
	)

Parse an I/O response and store it in an xbee_io_t structure.

Parameters

[out]	parsed	Result structure
[in]	source	Pointer to the start of the data i.e. the num_samples field of the I/O response.

Todo:

: the 0x0F constant is an artifact of the sharing of AD0-3 with

References be16toh, EINVAL, and FAR.

Referenced by _sxa_io_process_response().

int xbee_io_set_digital_output	(	xbee_dev_t *	xbee,
		xbee_io_t FAR *	io,
		uint_fast8_t	index,
		enum xbee_io_digital_output_state	state,
		const wpan_address_t FAR *	address
	)

Set state of a digital output.

This modifies the shadow state in the io parameter, as well as sending the appropriate configuration command to the target device. If the new state is the same as the shadow state, then the function returns without doing anything, unless XBEE_IO_FORCE is specified in the state parameter.

Parameters

[in,out]	xbee	local device through which to action the request
[in,out]	io	pointer to an xbee_io_t structure as set up by xbee_io_query(). Shadow state of I/O may be modified
[in]	index	digital output number e.g. 0 for DIO0, 2 for DIO2.
[in]	state	new state of I/O. If the XBEE_IO_FORCE flag is ORed in, then force a state update to the device, whether or not configured as an input or with shadow state unchanged. This can be used to initially configure and set a digital output. Otherwise, a state change will only be sent to the device if the shadow (i.e. last known) state is opposite AND the I/O is configured as a digital output.
[in]	address	NULL for local XBee, or destination IEEE (64-bit) or network (16 bit) address of a remote device. See wpan_envelope_create() for use of IEEE and network addressing.

Return values

0	Output low
1	Output high
-EINVAL	Output unknown because not configured as a digital output (and force was not specified), or is a non-existent output index, or bad parameter passed.
<0	Other negative value indicates problem transmitting the configuration request.

References EINVAL, FAR, xbee_cmd_create(), xbee_cmd_send(), xbee_cmd_set_param(), xbee_cmd_set_target(), XBEE_IO_FORCE, XBEE_IO_SET_HIGH, XBEE_IO_SET_LOW, and XBEE_IO_TYPE_MASK.

Referenced by _sxa_io_process_response().

int xbee_io_set_options	(	xbee_dev_t *	xbee,
		xbee_io_t FAR *	io,
		uint16_t	sample_rate,
		uint16_t	change_mask,
		const wpan_address_t FAR *	address
	)

Configure XBee automatic I/O sampling options.

This basically controls the ATIR and ATIC settings. IR specifies an automatic sampling interval, and IC specifies sampling on digital I/O change.

Parameters

[in,out]	xbee	local device through which to action the request
[in,out]	io	pointer to an xbee_io_t structure as set up by xbee_io_query(). Shadow state of I/O may be modified
[in]	sample_rate	sample period in ms. 0 to turn off sampling, otherwise must be a value geater than XBEE_IO_MIN_SAMPLE_PERIOD (50 ms with current hardware).
[in]	change_mask	bitmask of I/Os which are to generate samples when their state changes. Construct from ORed combination of XBEE_IO_DIO0, XBEE_IO_DIO1 etc.
[in]	address	NULL for local XBee, or destination IEEE (64-bit) or network (16 bit) address of a remote device.

Return values

0	Success
-EINVAL	Bad parameter.
-EPERM	Specified sampling rate or I/O bitmask not supported.
<0	Other negative value indicates problem transmitting the configuration request.

References EINVAL, EPERM, xbee_cmd_create(), xbee_cmd_send(), xbee_cmd_set_param(), xbee_cmd_set_target(), and XBEE_IO_MIN_SAMPLE_PERIOD.

Referenced by _sxa_io_process_response().

Variable Documentation

const xbee_atcmd_reg_t _xbee_io_query_regs[]

Initial value:

= {
   XBEE_ATCMD_REG( 'D', '0', XBEE_CLT_COPY, xbee_io_t, config[0]),
   XBEE_ATCMD_REG( 'D', '1', XBEE_CLT_COPY, xbee_io_t, config[1]),
   XBEE_ATCMD_REG( 'D', '2', XBEE_CLT_COPY, xbee_io_t, config[2]),
   XBEE_ATCMD_REG( 'D', '3', XBEE_CLT_COPY, xbee_io_t, config[3]),
   XBEE_ATCMD_REG( 'D', '4', XBEE_CLT_COPY, xbee_io_t, config[4]),
   XBEE_ATCMD_REG( 'D', '5', XBEE_CLT_COPY, xbee_io_t, config[5]),
   XBEE_ATCMD_REG( 'D', '6', XBEE_CLT_COPY, xbee_io_t, config[6]),
   XBEE_ATCMD_REG( 'D', '7', XBEE_CLT_COPY, xbee_io_t, config[7]),
   XBEE_ATCMD_REG( 'P', '0', XBEE_CLT_COPY, xbee_io_t, config[10]),
   XBEE_ATCMD_REG( 'P', '1', XBEE_CLT_COPY, xbee_io_t, config[11]),
   XBEE_ATCMD_REG( 'P', '2', XBEE_CLT_COPY, xbee_io_t, config[12]),
   XBEE_ATCMD_REG_CB( 'P', 'R', _xbee_io_query_handle_pr, 0),
   XBEE_ATCMD_REG( 'I', 'R', XBEE_CLT_COPY_BE, xbee_io_t, sample_rate),
   XBEE_ATCMD_REG( 'I', 'C', XBEE_CLT_COPY_BE, xbee_io_t, change_mask),

}

const uint16_t _xbee_pullup_atcmd_to_iomask[16]

Initial value:

=
{
   
   
   1u<<4,
   1u<<3,
   1u<<2,
   1u<<1,
   1u<<0,
   1u<<6,
   1u<<8,
   0,       
   1u<<5,
   1u<<9,
   1u<<12,
   1u<<10,
   1u<<11,
   1u<<7,
   0,
   0
}

Read current configuration of XBee digital and analog I/Os.

This sets the shadow state in the io parameter by querying the device configuration with a sequence of AT commands (D0,D0,...P0,...,PR). Unless the application has prior knowledge of the I/O config, this function should be used when a new node is discovered.

Since several commands must be executed, the results are not available immediately on return from this function. Instead, the application must call xbee_io_query_status() in order to poll for command completion.

Parameters

[in,out]	xbee	local device through which to action the request
[in,out]	io	pointer to an xbee_io_t structure, which will be modified by this call. Since the results are returned asynchronously, the data pointed to must be static.
[in]	address	NULL for local XBee, or destination IEEE (64-bit) or network (16 bit) address of a remote device.

Return values

0	Success
-EINVAL	Bad parameter.
-EBUSY	Device is currently busy with another request for this device. Try again later (after calling xbee_cmd_tick()). In general, several get configuration requests can run simultaneously, however only one per remote device.
<0	Other negative value indicates problem transmitting the configuration query commands.

See also

xbee_io_query_status()

const FAR xbee_at_cmd_t xbee_io_cmd_by_index[16]

Initial value:

=
{
   {{'D','0'}},
   {{'D','1'}},
   {{'D','2'}},
   {{'D','3'}},
   {{'D','4'}},
   {{'D','5'}},
   {{'\0','\0'}},
   {{'\0','\0'}},
   {{'D','8'}},
   {{'\0','\0'}},
   {{'P','0'}},
   {{'P','1'}},
   {{'P','2'}},
   {{'P','3'}},
}