This module contains drivers for radio devices in Microchip MRF24J40 series. More...

Detailed Description

This module contains drivers for radio devices in Microchip MRF24J40 series.

The driver is aimed to work with all devices of this series.

Warning: This driver doesn't handle the wake pin. As of now, it is required that the wake pin is high prior to the initialization (e.g. by connecting it to VCC in the board design).

Note: A PR extending mrf24j40_params_t to contain the wake pin and adding appropriate handling of the wake pin to the driver logic would be a welcome addition.

Default TX power is 0dBm.

TX power mapping:

0 -> -36dB
1 -> -35dB
2 -> -34dB
3 -> -33dB
4 -> -32dB
5 -> -31dB
6 -> -30dB
7 -> -30dB
8 -> -26dB
9 -> -25dB
10 -> -24dB
11 -> -23dB
12 -> -22dB
13 -> -21dB
14 -> -20dB
15 -> -20dB
16 -> -16dB
17 -> -15dB
18 -> -14dB
19 -> -13dB
20 -> -12dB
21 -> -11dB
22 -> -10dB
23 -> -10dB
24 -> -6dB
25 -> -5dB
26 -> -4dB
27 -> -3dB
28 -> -2dB
29 -> -1dB
30 -> -0dB
31 -> -0dB

Modules
	mrf24j40 driver compile configuration

Files
file	mrf24j40.h
	Interface definition for MRF24J40 based drivers .

file	mrf24j40_internal.h
	Internal interfaces for MRF24J40 drivers.

file	mrf24j40_netdev.h
	Netdev interface to MRF24J40 drivers.

file	mrf24j40_params.h
	Default configuration for the MRF24J40 driver.

file	mrf24j40_registers.h
	Register and command definitions for MRF24J40 devices.

Data Structures
struct	mrf24j40_params
	struct holding all params needed for device initialization More...

struct	mrf24j40_t
	Device descriptor for MRF24J40 radio devices. More...

Macros
#define	MRF24J40_TASK_TX_DONE (0x01)
	TX operation is done.

#define	MRF24J40_TASK_TX_READY (0x02)
	TX operation results ready for processing.

#define	MRF24J40_TASK_RX_READY (0x04)
	RX processing needed.

#define	MRF24J40_MAX_FRAME_RETRIES (3U)
	Number of frame retries (fixed)

#define	MRF24J40_MAX_MINBE (3U)
	Maximum value of minimum exponential backoff.

#define	MRF24J40_MIN_TXPOWER (-36)
	Minimum transmission power (dBm)

#define	MRF24J40_MAX_TXPOWER (0)
	Maximum transmission power (dBm)

Typedefs
typedef struct mrf24j40_params	mrf24j40_params_t
	struct holding all params needed for device initialization

Functions
int	mrf24j40_reset (mrf24j40_t *dev)
	Trigger a hardware reset and configure radio with default values.

void	mrf24j40_set_addr_short (mrf24j40_t *dev, uint16_t addr)
	Set the short address of the given device.

void	mrf24j40_set_addr_long (mrf24j40_t dev, const uint8_t addr)
	Set the long address of the given device.

uint8_t	mrf24j40_get_chan (mrf24j40_t *dev)
	Get the configured channel number of the given device.

void	mrf24j40_set_chan (mrf24j40_t *dev, uint8_t chan)
	Set the channel number of the given device.

uint16_t	mrf24j40_get_pan (mrf24j40_t *dev)
	Get the configured PAN ID of the given device.

void	mrf24j40_set_pan (mrf24j40_t *dev, uint16_t pan)
	Set the PAN ID of the given device.

void	mrf24j40_set_txpower (mrf24j40_t *dev, int16_t txpower)
	Set the transmission power of the given device [in dBm].

void	mrf24j40_set_csma_max_retries (mrf24j40_t *dev, int8_t retries)
	Set the maximum number of channel access attempts per frame (CSMA)

void	mrf24j40_set_csma_backoff_exp (mrf24j40_t *dev, uint8_t min, uint8_t max)
	Set the min and max backoff exponent for CSMA/CA.

void	mrf24j40_set_cca_threshold (mrf24j40_t *dev, int8_t value)
	Set the CCA threshold value.

void	mrf24j40_set_option (mrf24j40_t *dev, uint16_t option, bool state)
	Enable or disable driver specific options.

void	mrf24j40_set_state (mrf24j40_t *dev, uint8_t state)
	Set the state of the given device (trigger a state change)

void	mrf24j40_set_turbo (mrf24j40_t *dev, bool enable)
	Enable or disable proprietary Turbo Mode.

void	mrf24j40_sleep (mrf24j40_t *dev)
	Put in sleep mode.

void	mrf24j40_wake_up (mrf24j40_t *dev)
	Wake up from sleep mode.

void	mrf24j40_reset_state_machine (mrf24j40_t *dev)
	Reset the internal state machine to TRX_OFF mode.

void	mrf24j40_software_reset (mrf24j40_t *dev)
	Software Reset.

int8_t	mrf24j40_dbm_from_reg (uint8_t value)
	Convert scalar from mrf24j40 RSSI to dBm.

void	mrf24j40_tx_prepare (mrf24j40_t *dev)
	Prepare for sending of data.

size_t	mrf24j40_tx_load (mrf24j40_t dev, uint8_t data, size_t len, size_t offset)
	Load chunks of data into the transmit buffer of the given device.

void	mrf24j40_tx_exec (mrf24j40_t *dev)
	Trigger sending of data previously loaded into transmit buffer.

void	mrf24j40_radio_irq_handler (void *dev)
	IRQ Handler for the MRF24J40 device.

int	mrf24j40_init (mrf24j40_t dev, const mrf24j40_params_t params, ieee802154_dev_t hal, gpio_cb_t cb, void ctx)
	Initialize the given MRF24J40 device.

Flags for pseudo device internal states
#define	MRF24J40_PSEUDO_STATE_IDLE (0x01)
	Idle, ready to transmit or receive.

#define	MRF24J40_PSEUDO_STATE_SLEEP (0x02)
	sleep mode, registers functional, but no RF

#define	MRF24J40_PSEUDO_STATE_RESET (0x04)
	Reset device, next state is idle.

Internal device option flags
`0x00ff` is reserved for general IEEE 802.15.4 flags (see netdev_ieee802154_t)
#define	MRF24J40_OPT_CSMA (0x0100)
	CSMA active.

#define	MRF24J40_OPT_PROMISCUOUS (0x0200)
	promiscuous mode active

#define	MRF24J40_OPT_PRELOADING (0x0400)
	preloading enabled

Macro Definition Documentation

◆ MRF24J40_MAX_FRAME_RETRIES

#define MRF24J40_MAX_FRAME_RETRIES (3U)

Number of frame retries (fixed)

Definition at line 114 of file mrf24j40.h.

◆ MRF24J40_MAX_MINBE

#define MRF24J40_MAX_MINBE (3U)

Maximum value of minimum exponential backoff.

Definition at line 117 of file mrf24j40.h.

◆ MRF24J40_MAX_TXPOWER

#define MRF24J40_MAX_TXPOWER (0)

Maximum transmission power (dBm)

Definition at line 119 of file mrf24j40.h.

◆ MRF24J40_MIN_TXPOWER

#define MRF24J40_MIN_TXPOWER (-36)

Minimum transmission power (dBm)

Definition at line 118 of file mrf24j40.h.

◆ MRF24J40_OPT_CSMA

#define MRF24J40_OPT_CSMA (0x0100)

CSMA active.

Definition at line 104 of file mrf24j40.h.

◆ MRF24J40_OPT_PRELOADING

#define MRF24J40_OPT_PRELOADING (0x0400)

preloading enabled

Definition at line 107 of file mrf24j40.h.

◆ MRF24J40_OPT_PROMISCUOUS

#define MRF24J40_OPT_PROMISCUOUS (0x0200)

promiscuous mode active

Definition at line 106 of file mrf24j40.h.

◆ MRF24J40_PSEUDO_STATE_IDLE

#define MRF24J40_PSEUDO_STATE_IDLE (0x01)

Idle, ready to transmit or receive.

Definition at line 91 of file mrf24j40.h.

◆ MRF24J40_PSEUDO_STATE_RESET

#define MRF24J40_PSEUDO_STATE_RESET (0x04)

Reset device, next state is idle.

Definition at line 93 of file mrf24j40.h.

◆ MRF24J40_PSEUDO_STATE_SLEEP

#define MRF24J40_PSEUDO_STATE_SLEEP (0x02)

sleep mode, registers functional, but no RF

Definition at line 92 of file mrf24j40.h.

◆ MRF24J40_TASK_RX_READY

#define MRF24J40_TASK_RX_READY (0x04)

RX processing needed.

Definition at line 112 of file mrf24j40.h.

◆ MRF24J40_TASK_TX_DONE

#define MRF24J40_TASK_TX_DONE (0x01)

TX operation is done.

Definition at line 110 of file mrf24j40.h.

◆ MRF24J40_TASK_TX_READY

#define MRF24J40_TASK_TX_READY (0x02)

TX operation results ready for processing.

Definition at line 111 of file mrf24j40.h.

Function Documentation

◆ mrf24j40_dbm_from_reg()

int8_t mrf24j40_dbm_from_reg ( uint8_t value )

Convert scalar from mrf24j40 RSSI to dBm.

Parameters

[in] value value to convert to dBm

Returns: converted value in dBm

◆ mrf24j40_get_chan()

uint8_t mrf24j40_get_chan ( mrf24j40_t * dev )

Get the configured channel number of the given device.

Parameters

[in] dev device to read from

Returns: the currently set channel number

◆ mrf24j40_get_pan()

uint16_t mrf24j40_get_pan ( mrf24j40_t * dev )

Get the configured PAN ID of the given device.

Parameters

[in] dev device to read from

Returns: the currently set PAN ID

◆ mrf24j40_init()

int mrf24j40_init	(	mrf24j40_t *	dev,
		const mrf24j40_params_t *	params,
		ieee802154_dev_t *	hal,
		gpio_cb_t	cb,
		void *	ctx
	)

Initialize the given MRF24J40 device.

Parameters

[out]	dev	device descriptor
[in]	params	parameters for device initialization
[in]	hal	pointer to IEEE 802.15.4 Radio HAL descriptor
[in]	cb	ISR callback
[in]	ctx	context pointer handed to isr

Returns: 0 on success; <0 on error

◆ mrf24j40_radio_irq_handler()

void mrf24j40_radio_irq_handler ( void * dev )

IRQ Handler for the MRF24J40 device.

Parameters

[in] dev pointer to the IEEE 802.15.4 Radio HAL descriptor

◆ mrf24j40_reset()

int mrf24j40_reset ( mrf24j40_t * dev )

Trigger a hardware reset and configure radio with default values.

Parameters

[in] dev device to reset

Returns: 0 on success, error otherwise

◆ mrf24j40_reset_state_machine()

void mrf24j40_reset_state_machine ( mrf24j40_t * dev )

Reset the internal state machine to TRX_OFF mode.

This will force a transition to TRX_OFF regardless of whether the transceiver is currently busy sending or receiving. This function is used to get back to a known state during driver initialization.

Parameters

[in] dev device to operate on

◆ mrf24j40_set_addr_long()

void mrf24j40_set_addr_long	(	mrf24j40_t *	dev,
		const uint8_t *	addr
	)

Set the long address of the given device.

Parameters

[in]	dev	device to write to
[in]	addr	(8-byte) long address to set

◆ mrf24j40_set_addr_short()

void mrf24j40_set_addr_short	(	mrf24j40_t *	dev,
		uint16_t	addr
	)

Set the short address of the given device.

Parameters

[in]	dev	device to write to
[in]	addr	(2-byte) short address to set

◆ mrf24j40_set_cca_threshold()

void mrf24j40_set_cca_threshold	(	mrf24j40_t *	dev,
		int8_t	value
	)

Set the CCA threshold value.

Parameters

[in]	dev	device to write to
[in]	value	the new CCA threshold value

◆ mrf24j40_set_chan()

void mrf24j40_set_chan	(	mrf24j40_t *	dev,
		uint8_t	chan
	)

Set the channel number of the given device.

Parameters

[in]	dev	device to write to
[in]	chan	channel number to set

◆ mrf24j40_set_csma_backoff_exp()

void mrf24j40_set_csma_backoff_exp	(	mrf24j40_t *	dev,
		uint8_t	min,
		uint8_t	max
	)

Set the min and max backoff exponent for CSMA/CA.

Maximum BE: 0 - 8
Minimum BE: 0 - [max]

Parameters

[in]	dev	device to write to
[in]	min	the minimum BE
[in]	max	the maximum BE

◆ mrf24j40_set_csma_max_retries()

void mrf24j40_set_csma_max_retries	(	mrf24j40_t *	dev,
		int8_t	retries
	)

Set the maximum number of channel access attempts per frame (CSMA)

This setting specifies the number of attempts to access the channel to transmit a frame. If the channel is busy retries times, then frame transmission fails. Valid values: 0 to 5, -1 means CSMA disabled

Parameters

[in]	dev	device to write to
[in]	retries	the maximum number of retries

◆ mrf24j40_set_option()

void mrf24j40_set_option	(	mrf24j40_t *	dev,
		uint16_t	option,
		bool	state
	)

Enable or disable driver specific options.

Parameters

[in]	dev	device to set/clear option flag for
[in]	option	option to enable/disable
[in]	state	true for enable, false for disable

◆ mrf24j40_set_pan()

void mrf24j40_set_pan	(	mrf24j40_t *	dev,
		uint16_t	pan
	)

Set the PAN ID of the given device.

Parameters

[in]	dev	device to write to
[in]	pan	PAN ID to set

◆ mrf24j40_set_state()

void mrf24j40_set_state	(	mrf24j40_t *	dev,
		uint8_t	state
	)

Set the state of the given device (trigger a state change)

Parameters

[in]	dev	device to change state of
[in]	state	the targeted new state

◆ mrf24j40_set_turbo()

void mrf24j40_set_turbo	(	mrf24j40_t *	dev,
		bool	enable
	)

Enable or disable proprietary Turbo Mode.

Turbo mode is only compatible with other mrf24j40 chips.

turbo off: 250 kbit/s (IEEE mode) turbo on: 625 kbit/s

Parameters

[in]	dev	device to change state of
[in]	enable	turbo mode control

◆ mrf24j40_set_txpower()

void mrf24j40_set_txpower	(	mrf24j40_t *	dev,
		int16_t	txpower
	)

Set the transmission power of the given device [in dBm].

If the device does not support the exact dBm value given, it will set a value as close as possible to the given value. If the given value is larger or lower then the maximal or minimal possible value, the min or max value is set, respectively.

Parameters

[in]	dev	device to write to
[in]	txpower	transmission power in dBm

◆ mrf24j40_sleep()

void mrf24j40_sleep ( mrf24j40_t * dev )

Put in sleep mode.

Parameters

[in] dev device to put to sleep

◆ mrf24j40_software_reset()

void mrf24j40_software_reset ( mrf24j40_t * dev )

Software Reset.

This will force the power management circuitry, the baseband circuitry and the MAC circuitry to be reset

Parameters

[in] dev device to operate on

◆ mrf24j40_tx_exec()

void mrf24j40_tx_exec ( mrf24j40_t * dev )

Trigger sending of data previously loaded into transmit buffer.

Parameters

[in] dev device to trigger

◆ mrf24j40_tx_load()

size_t mrf24j40_tx_load	(	mrf24j40_t *	dev,
		uint8_t *	data,
		size_t	len,
		size_t	offset
	)

Load chunks of data into the transmit buffer of the given device.

Parameters

[in]	dev	device to write data to
[in]	data	buffer containing the data to load
[in]	len	number of bytes in `buffer`
[in]	offset	offset used when writing data to internal buffer

Returns: offset + number of bytes written

◆ mrf24j40_tx_prepare()

void mrf24j40_tx_prepare ( mrf24j40_t * dev )

Prepare for sending of data.

This function puts the given device into the TX state, so no receiving of data is possible after it was called.

Parameters

[in] dev device to prepare for sending

◆ mrf24j40_wake_up()

void mrf24j40_wake_up ( mrf24j40_t * dev )

Wake up from sleep mode.

Parameters

[in] dev device to eventually wake up

Detailed Description

Modules

Files

Data Structures

Macros

Typedefs

Functions

Flags for pseudo device internal states

Internal device option flags

Macro Definition Documentation

◆ MRF24J40_MAX_FRAME_RETRIES

◆ MRF24J40_MAX_MINBE

◆ MRF24J40_MAX_TXPOWER

◆ MRF24J40_MIN_TXPOWER

◆ MRF24J40_OPT_CSMA

◆ MRF24J40_OPT_PRELOADING

◆ MRF24J40_OPT_PROMISCUOUS

◆ MRF24J40_PSEUDO_STATE_IDLE

◆ MRF24J40_PSEUDO_STATE_RESET

◆ MRF24J40_PSEUDO_STATE_SLEEP

◆ MRF24J40_TASK_RX_READY

◆ MRF24J40_TASK_TX_DONE

◆ MRF24J40_TASK_TX_READY

Function Documentation

◆ mrf24j40_dbm_from_reg()

◆ mrf24j40_get_chan()

◆ mrf24j40_get_pan()

◆ mrf24j40_init()

◆ mrf24j40_radio_irq_handler()

◆ mrf24j40_reset()

◆ mrf24j40_reset_state_machine()

◆ mrf24j40_set_addr_long()

◆ mrf24j40_set_addr_short()

◆ mrf24j40_set_cca_threshold()

◆ mrf24j40_set_chan()

◆ mrf24j40_set_csma_backoff_exp()

◆ mrf24j40_set_csma_max_retries()

◆ mrf24j40_set_option()

◆ mrf24j40_set_pan()

◆ mrf24j40_set_state()

◆ mrf24j40_set_turbo()

◆ mrf24j40_set_txpower()

◆ mrf24j40_sleep()

◆ mrf24j40_software_reset()

◆ mrf24j40_tx_exec()

◆ mrf24j40_tx_load()

◆ mrf24j40_tx_prepare()

◆ mrf24j40_wake_up()