twi.h File Reference

nRF51-specific support for I2C More...

#include <bspacm/core.h>

Go to the source code of this file.

Data Structures
struct	sBSPACMi2cBus

Macros
#define	BSPACM_NRF_TWI_BUS_ERROR_TIMEOUT   0x100
#define	BSPACM_NRF_TWI_BUS_ERROR_CLEAR_FAILED   0x200
#define	BSPACM_NRF_TWI_BUS_ERROR_UNKNOWN   0x400
#define	BSPACM_NRF_APPLY_PAN_36   1
#define	BSPACM_NRF_APPLY_PAN_56   1
#define	BSPACM_I2C_MINIMUM_BUS_TIMEOUT_us   100

Typedefs
typedef struct sBSPACMi2cBus	sBSPACMi2cBus
typedef const sBSPACMi2cBus *	hBSPACMi2cBus

Functions
hBSPACMi2cBus	hBSPACMi2cConfigureBus (sBSPACMi2cBus *tpp, NRF_TWI_Type *twi, int sda_pin, int scl_pin, int ppi_chidx, uint32_t frequency, unsigned int timeout_us)
int	iBSPACMi2cSetEnabled (hBSPACMi2cBus tpp, bool enabled)
int	iBSPACMi2cRead (hBSPACMi2cBus tpp, unsigned int addr, uint8_t *dp, size_t len)
int	iBSPACMi2cWrite (hBSPACMi2cBus tpp, unsigned int addr, const uint8_t *sp, size_t len)

Detailed Description

nRF51-specific support for I2C

Nordic calls this "TWI", but it's I2C so that's what the API uses.

Note

The implementation depends on <bspacm/utility/hires.h> and <bspacm/utility/uptime.h>

Homepage

http://github.com/pabigot/bspacm

Copyright

Copyright 2015, Peter A. Bigot. Licensed under BSD-3-Clause

Macro Definition Documentation

#define BSPACM_I2C_MINIMUM_BUS_TIMEOUT_us   100

The minimum acceptable per-byte timeout for I2C bus transactions, in microseconds.

#define BSPACM_NRF_APPLY_PAN_36   1

PAN #36: Shortcuts are not functional Use PPI channel to enforce BB to SUSPEND and STOP tasks.

Define to C preprocessor true value to enable workaround. This impacts the accepted parameters of hBSPACMi2cConfigureBus().

C Preprocessor Only:

This macro may have a value that restricts its use to C preprocessor conditional directives.

#define BSPACM_NRF_APPLY_PAN_56   1

PAN #56: module lock-up

Various conditions require a full power-cycle of the TWI module to restore functionality. The likelihood of occurrence can be lessened by certain behaviors, but in the end we need to alarm if an expected RXDREADY or TXDREADY signal is not received in a timely manner.

If enabled by defining to a C preprocessor true value the recovery from I2C bus timeouts will include power-cycling the TWI peripheral.

C Preprocessor Only:

This macro may have a value that restricts its use to C preprocessor conditional directives.

#define BSPACM_NRF_TWI_BUS_ERROR_CLEAR_FAILED   0x200

Bit set in absolute value of an error return code when the I2C bus is being held by an unresponsive follower device and the master failed to clear the hold.

#define BSPACM_NRF_TWI_BUS_ERROR_TIMEOUT   0x100

Bit set in absolute value of an error return code when a bus timeout was discovered. If BSPACM_NRF_APPLY_PAN_56 is enabled the TWI peripheral will have been power cycled to ensure recovery.

#define BSPACM_NRF_TWI_BUS_ERROR_UNKNOWN   0x400

Bit set in absolute value of an error return code when the I2C peripheral indicated an error, but the error cause could not be identified.

Typedef Documentation

typedef const sBSPACMi2cBus* hBSPACMi2cBus

A handle for a bus configuration

Function Documentation

hBSPACMi2cBus hBSPACMi2cConfigureBus	(	sBSPACMi2cBus *	tpp,
		NRF_TWI_Type *	twi,
		int	sda_pin,
		int	scl_pin,
		int	ppi_chidx,
		uint32_t	frequency,
		unsigned int	timeout_us
	)

Configure the I2C bus structure.

This validates and records all non-address bus configuration data. It does not configure or enable the bus itself.

Parameters

tpp	pointer to the bus structure
twi	the NRF TWI peripheral used by the bus; generally #NRF_TWI0 or #NRF_TWI1.
sda_pin	the pin number to used for the I2C SDA functionality.
scl_pin	the pin number to used for the I2C SCL functionality.
ppi_chidx	The Programmable Peripheral Interconnect channel used to support the workaround for PAN #36. If BSPACM_NRF_APPLY_PAN_36 is enabled this must be a PPI channel (0..15). If BSPACM_NRF_APPLY_PAN_36 is disabled this must be -1.
frequency	the bus frequency, expressed as the value of the NRF_TWI_Type::FREQUENCY register. E.g. #TWI_FREQUENCY_FREQUENCY_K400.
timeout_us	The maximum time the bus will wait for #TXDREADY or #RXDREADY from a follower device. This relates to BSPACM_NRF_APPLY_PAN_56 but has the specified effect even if that PAN is not enabled. The timeout is reset on each successful byte transfer, and is implemented as a busy-wait. Remember to account for clock stretching. Values less than BSPACM_I2C_MINIMUM_BUS_TIMEOUT_us are adjusted to meet that minimum.

Returns

tpp as handle if the configuration was acceptable, or NULL if a parameter was rejected.

BSPACM_NRF_APPLY_PAN_36

int iBSPACMi2cRead	(	hBSPACMi2cBus	tpp,
		unsigned int	addr,
		uint8_t *	dp,
		size_t	len
	)

Read data from the I2C bus.

Parameters

tpp	the bus to use
addr	the address of the device from which data will be read. This is the 7-bit address, exclusive of the RW bit.
dp	where the requested data should be stored
len	the number of bytes to be read

Returns

len on success, otherwise a negative error code.

int iBSPACMi2cSetEnabled	(	hBSPACMi2cBus	tpp,
		bool	enabled
	)

Enable or disable the TWI bus configuration.

Returns

Zero if enable (or disable) was successful, otherwise a negative error code. Errors can occur when failing to gain control of a newly enabled bus.

int iBSPACMi2cWrite	(	hBSPACMi2cBus	tpp,
		unsigned int	addr,
		const uint8_t *	sp,
		size_t	len
	)

Write data to the I2C bus.

Parameters

tpp	the bus to use
addr	the address of the device to which data will be written. This is the 7-bit address, exclusive of the RW bit.
sp	pointer to the data to be written
len	the number of bytes to write

Returns

len on success, otherwise a negative error code.