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.

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)

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

Functions
void	mrf24j40_setup (mrf24j40_t dev, const mrf24j40_params_t params, uint8_t index)
	Setup an MRF24J40 based device state. More...

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

bool	mrf24j40_cca (mrf24j40_t dev, int8_t rssi)
	Trigger a clear channel assessment & retrieve RSSI. More...

uint16_t	mrf24j40_get_addr_short (mrf24j40_t *dev)
	Get the short address of the given device. More...

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

void	mrf24j40_get_addr_long (mrf24j40_t dev, uint8_t addr)
	Get the configured long address of the given device. More...

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

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

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

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

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

int16_t	mrf24j40_get_txpower (mrf24j40_t *dev)
	Get the configured transmission power of the given device [in dBm]. More...

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

uint8_t	mrf24j40_get_csma_max_retries (mrf24j40_t *dev)
	Get the maximum number of channel access attempts per frame (CSMA) More...

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

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. More...

int8_t	mrf24j40_get_cca_threshold (mrf24j40_t *dev)
	Get the CCA threshold value. More...

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

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

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

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

bool	mrf24j40_get_turbo (mrf24j40_t *dev)
	Query the state of the turbo mode. More...

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

void	mrf24j40_assert_sleep (mrf24j40_t *dev)
	Put in sleep mode if idle_state is sleep. More...

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

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

void	mrf24j40_software_reset (mrf24j40_t *dev)
	Software Reset. More...

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

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

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. More...

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

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

#define	MRF24J40_OPT_TELL_TX_START (0x0800)
	notify MAC layer on TX start

#define	MRF24J40_OPT_TELL_TX_END (0x1000)
	notify MAC layer on TX finished

#define	MRF24J40_OPT_TELL_RX_START (0x2000)
	notify MAC layer on RX start

#define	MRF24J40_OPT_TELL_RX_END (0x4000)
	notify MAC layer on RX finished

#define	MRF24J40_OPT_REQ_AUTO_ACK (0x8000)
	notify MAC layer on RX finished

Function Documentation

◆ mrf24j40_assert_awake()

void mrf24j40_assert_awake ( mrf24j40_t * dev )

Wake up from sleep mode.

Parameters

[in] dev device to eventually wake up

◆ mrf24j40_assert_sleep()

void mrf24j40_assert_sleep ( mrf24j40_t * dev )

Put in sleep mode if idle_state is sleep.

Parameters

[in] dev device to put to sleep

◆ mrf24j40_cca()

bool mrf24j40_cca	(	mrf24j40_t *	dev,
		int8_t *	rssi
	)

Trigger a clear channel assessment & retrieve RSSI.

Parameters

[in]	dev	device to use
[in]	rssi	RSSI value from register in dBm

Returns: true if channel is clear; false if channel is busy

◆ 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_addr_long()

void mrf24j40_get_addr_long	(	mrf24j40_t *	dev,
		uint8_t *	addr
	)

Get the configured long address of the given device.

Parameters

[in]	dev	device to read from
[out]	addr	the currently set (8-byte) long address

◆ mrf24j40_get_addr_short()

uint16_t mrf24j40_get_addr_short ( mrf24j40_t * dev )

Get the short address of the given device.

Parameters

[in] dev device to read from

Returns: the currently set (2-byte) short address

◆ mrf24j40_get_cca_threshold()

int8_t mrf24j40_get_cca_threshold ( mrf24j40_t * dev )

Get the CCA threshold value.

Parameters

[in] dev device to read value from

Returns: the current CCA threshold value

◆ 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_csma_max_retries()

uint8_t mrf24j40_get_csma_max_retries ( mrf24j40_t * dev )

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

Parameters

[in] dev device to read from

Returns: configured number of retries

◆ 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_get_turbo()

bool mrf24j40_get_turbo ( mrf24j40_t * dev )

Query the state of the turbo mode.

Parameters

[in] dev device to query

Returns: true if Turbo Mode is enabled

◆ mrf24j40_get_txpower()

int16_t mrf24j40_get_txpower ( mrf24j40_t * dev )

Get the configured transmission power of the given device [in dBm].

Parameters

[in] dev device to read from

Returns: configured transmission power in dBm

◆ 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_setup()

void mrf24j40_setup	(	mrf24j40_t *	dev,
		const mrf24j40_params_t *	params,
		uint8_t	index
	)

Setup an MRF24J40 based device state.

Parameters

[out]	dev	device descriptor
[in]	params	parameters for device initialization
[in]	index	index of `params` in a global parameter struct array. If initialized manually, pass a unique identifier instead.

◆ 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

Detailed Description

Modules

Files

Data Structures

Macros

Typedefs

Functions

Flags for pseudo device internal states

Internal device option flags

Function Documentation

◆ mrf24j40_assert_awake()

◆ mrf24j40_assert_sleep()

◆ mrf24j40_cca()

◆ mrf24j40_dbm_from_reg()

◆ mrf24j40_get_addr_long()

◆ mrf24j40_get_addr_short()

◆ mrf24j40_get_cca_threshold()

◆ mrf24j40_get_chan()

◆ mrf24j40_get_csma_max_retries()

◆ mrf24j40_get_pan()

◆ mrf24j40_get_turbo()

◆ mrf24j40_get_txpower()

◆ 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_setup()

◆ mrf24j40_sleep()

◆ mrf24j40_software_reset()

◆ mrf24j40_tx_exec()

◆ mrf24j40_tx_load()

◆ mrf24j40_tx_prepare()