A configuration structure for the CSMA transmit algorithm.
One of RAIL's schemes for polite spectrum access is an implementation of a Carrier-Sense Multiple Access (CSMA) algorithm based on IEEE 802.15.4 (unslotted).
In pseudo-code it works like this, showing relevant event notifications:
// Return true to transmit packet, false to not transmit packet.
bool performCsma(const RAIL_CsmaConfig_t *csmaConfig)
{
bool isFixedBackoff = ((csmaConfig->csmaMinBoExp == 0)
&& (csmaConfig->csmaMaxBoExp == 0));
int backoffExp = csmaConfig->csmaMinBoExp; // Initial backoff exponent
int backoffMultiplier = 1; // Assume fixed backoff
int try;
// Special-case tries == 0 to transmit immediately without backoff+CCA
if (csmaConfig->csmaTries == 0) {
return true;
}
// Start overall timeout if specified:
if (csmaConfig->csmaTimeout > 0) {
StartAbortTimer(csmaConfig->csmaTimeout, RAIL_EVENT_TX_CHANNEL_BUSY);
// If timeout occurs, abort and signal the indicated event.
}
for (try = 0; try < csmaConfig->csmaTries; try++) {
if (try > 0) {
signalEvent(RAIL_EVENT_TX_CCA_RETRY);
}
// Determine the backoff multipler for this try:
if (isFixedBackoff) {
// backoffMultiplier already set to 1 for fixed backoff
} else {
// Start with the backoff exponent for this try:
if (try > 0) {
backoffExp++;
if (backoffExp > csmaConfig->csmaMaxBoExp) {
backoffExp = csmaConfig->csmaMaxBoExp;
}
}
// Pick random multiplier between 0 and 2^backoffExp - 1 inclusive:
backoffMultiplier = pickRandomInteger(0, (1 << backoffExp) - 1);
}
// Perform the backoff:
delayMicroseconds(backoffMultiplier * csmaConfig->ccaBackoff);
// Perform the Clear-Channel Assessment (CCA):
// Channel is considered busy if radio is actively receiving or
// transmitting, or the average energy detected across duration
// is above the threshold.
signalEvent(RAIL_EVENT_TX_START_CCA);
if (performCca(csmaConfig->ccaDuration, csmaConfig->ccaThreshold)) {
// CCA (and CSMA) success: Transmit after RX-to-TX turnaround
StopAbortTimer();
signalEvent(RAIL_EVENT_TX_CHANNEL_CLEAR);
return true;
} else {
// CCA failed: loop to try again, or exit if out of tries
}
}
// Overall CSMA failure: Don't transmit
StopAbortTimer();
signalEvent(RAIL_EVENT_TX_CHANNEL_BUSY);
return false;
}
Public Attributes#
The minimum (starting) exponent for CSMA random backoff (2^exp - 1).
The maximum exponent for CSMA random backoff (2^exp - 1).
The number of backoff-then-CCA iterations that can fail before reporting RAIL_EVENT_TX_CHANNEL_BUSY.
The CCA RSSI threshold, in dBm, above which the channel is considered 'busy'.
The backoff unit period in RAIL's microsecond time base.
The minimum desired CCA check duration in microseconds.
An overall timeout, in RAIL's microsecond time base, for the operation.
Public Attribute Documentation#
csmaMinBoExp#
uint8_t RAIL_CsmaConfig_t::csmaMinBoExp
The minimum (starting) exponent for CSMA random backoff (2^exp - 1).
It can range from 0 to RAIL_MAX_CSMA_EXPONENT.
Warnings
On EFR32, due to a hardware limitation, this can only be 0 if csmaMaxBoExp is also 0 specifying a non-random fixed backoff. RAIL_STATUS_INVALID_PARAMETER will result otherwise. If you really want CSMA's first iteration to have no backoff prior to CCA, with subsequent iterations having random backoff as the exponent is increased, you must do a fixed backoff of 0 operation first (csmaMinBoExp = 0, csmaMaxBoExp = 0, ccaBackoff = 0, csmaTries = 1), and if that fails (RAIL_EVENT_TX_CHANNEL_BUSY), follow up with a random backoff operation starting at csmaMinBoExp = 1 for the remaining iterations.
3281
of file common/rail_types.h
csmaMaxBoExp#
uint8_t RAIL_CsmaConfig_t::csmaMaxBoExp
The maximum exponent for CSMA random backoff (2^exp - 1).
It can range from 0 to RAIL_MAX_CSMA_EXPONENT and must be greater than or equal to csmaMinBoExp.
If both exponents are 0, a non-random fixed backoff of ccaBackoff duration results.
3289
of file common/rail_types.h
csmaTries#
uint8_t RAIL_CsmaConfig_t::csmaTries
The number of backoff-then-CCA iterations that can fail before reporting RAIL_EVENT_TX_CHANNEL_BUSY.
Typically ranges from 1 to RAIL_MAX_LBT_TRIES; higher values are disallowed. A value 0 always transmits immediately without performing CSMA, similar to calling RAIL_StartTx().
3297
of file common/rail_types.h
ccaThreshold#
int8_t RAIL_CsmaConfig_t::ccaThreshold
The CCA RSSI threshold, in dBm, above which the channel is considered 'busy'.
3302
of file common/rail_types.h
ccaBackoff#
uint16_t RAIL_CsmaConfig_t::ccaBackoff
The backoff unit period in RAIL's microsecond time base.
It is multiplied by the random backoff exponential controlled by csmaMinBoExp and csmaMaxBoExp to determine the overall backoff period. For random backoffs, any value above 511 microseconds will be truncated. For fixed backoffs it can go up to 65535 microseconds.
3310
of file common/rail_types.h
ccaDuration#
uint16_t RAIL_CsmaConfig_t::ccaDuration
The minimum desired CCA check duration in microseconds.
The RSSI is averaged over this duration by default but can be set to use the peak RSSI, on supported platforms, using the RAIL_TX_OPTION_CCA_PEAK_RSSI option.
Note
Depending on the radio configuration, due to hardware constraints, the actual duration may be longer. Also, if the requested duration is too large for the radio to accommodate, RAIL_StartCcaCsmaTx() will fail returning RAIL_STATUS_INVALID_PARAMETER.
3321
of file common/rail_types.h
csmaTimeout#
RAIL_Time_t RAIL_CsmaConfig_t::csmaTimeout
An overall timeout, in RAIL's microsecond time base, for the operation.
If the transmission doesn't start before this timeout expires, the transmission will fail with RAIL_EVENT_TX_CHANNEL_BUSY. A value 0 means no timeout is imposed.
3328
of file common/rail_types.h