Module lorawan_device

Expand description

The C ABI for a LoRaWAN Class A end device, without a radio.

PamojaLorawanEndDevice wraps pamoja_lorawan::device::EndDevice: it joins, chooses a channel and data rate for each uplink, says when and where to listen for the answer, reads what comes back, and does what the network’s MAC commands ask. It owns no radio and no clock, so every call takes the time in microseconds and hands back what to put on the air.

A device lives as long as the program may keep it, so it runs on a published channel plan: a region from pamoja_lora_plan_for_region or a CN470-510 plan from pamoja_lora_plan_for_cn470. The plan handle may be freed once the device is made.

A call that fails returns a status and records why on the device. Read it with pamoja_lorawan_end_device_error, which says, for example, until when the air is not free.

Structs§

PamojaLorawanChannel: A channel a device may send on.
PamojaLorawanDeviceError: Why a device’s last call failed.
PamojaLorawanDeviceSettings: What a device’s radio can do, and how it takes part.
PamojaLorawanEndDevice: An opaque handle to a LoRaWAN Class A end device.
PamojaLorawanEndDeviceStatus: Where a device stands, read in one call.
PamojaLorawanHeard: What a frame heard in a receive window turned out to be.
PamojaLorawanNext: What to do once both receive windows closed with nothing for the device.
PamojaLorawanRelayExchange: The wake-on-radio exchange an uplink under a relay goes out behind, TS011-1.0.1 section 5.
PamojaLorawanRelayStatus: What a relay’s acknowledgment said about itself, TS011-1.0.1 table 14.
PamojaLorawanTransmission: A frame to put on the air, and where to listen afterward.
PamojaLorawanWindow: When and where to listen for a downlink.

Constants§

PAMOJA_LORAWAN_BATTERY_EXTERNAL: A device running from an external supply.
PAMOJA_LORAWAN_BATTERY_LEVEL: A device reporting a battery level from 1, empty, to 254, full.
PAMOJA_LORAWAN_BATTERY_UNKNOWN: A device that cannot measure its battery.
PAMOJA_LORAWAN_DEVICE_BUSY: A transmission is still waiting on its receive windows.
PAMOJA_LORAWAN_DEVICE_COUNTER_EXHAUSTED: The uplink frame counter is spent, and the device has to join again.
PAMOJA_LORAWAN_DEVICE_COUNTER_GAP: The frame counter jumped further ahead than the device follows.
PAMOJA_LORAWAN_DEVICE_DATA_RATE: The data rate data_rate is not a LoRa one the device can use.
PAMOJA_LORAWAN_DEVICE_FOREIGN: The frame is addressed to another device.
PAMOJA_LORAWAN_DEVICE_FRAME: The frame did not decode, or port 0 was asked for an application payload.
PAMOJA_LORAWAN_DEVICE_NOTHING_PENDING: There is no transmission waiting on its windows or due to repeat.
PAMOJA_LORAWAN_DEVICE_NOT_JOINED: The device has not joined.
PAMOJA_LORAWAN_DEVICE_NO_CHANNEL: No enabled channel carries the data rate.
PAMOJA_LORAWAN_DEVICE_NO_CREDENTIALS: A device activated by personalization has nothing to join with.
PAMOJA_LORAWAN_DEVICE_OK: The last call succeeded.
PAMOJA_LORAWAN_DEVICE_PAYLOAD_TOO_LONG: The payload does not fit; max bytes do.
PAMOJA_LORAWAN_DEVICE_REFUSED: A join accept carries settings the region does not allow.
PAMOJA_LORAWAN_DEVICE_REPLAYED: The frame repeats or precedes the last downlink the device accepted.
PAMOJA_LORAWAN_DEVICE_STATE: A saved state was not resumed; state says why.
PAMOJA_LORAWAN_DEVICE_TOO_MANY_CHANNELS: The plan defines more channels than a device keeps.
PAMOJA_LORAWAN_DEVICE_WAIT: The air is not free until until_us.
PAMOJA_LORAWAN_HEARD_DATA: A data frame for the device.
PAMOJA_LORAWAN_HEARD_JOINED: A join accept: the device is on the network.
PAMOJA_LORAWAN_NEXT_DONE: The uplink is finished.
PAMOJA_LORAWAN_NEXT_JOIN_AGAIN: The join got no answer; join again with a new nonce, no sooner than the time given.
PAMOJA_LORAWAN_NEXT_REPEAT: Send the same frame again, no sooner than the time given.
PAMOJA_LORAWAN_NEXT_UNACKNOWLEDGED: A confirmed uplink went out every time it may without an acknowledgment.
PAMOJA_LORAWAN_RELAY_DEVICE_CONTROLLED: Leave it to the device, which is where every device starts.
PAMOJA_LORAWAN_RELAY_DISABLED: Never send through a relay, TS011-1.0.1 table 40.
PAMOJA_LORAWAN_RELAY_DYNAMIC: Start using one after enough uplinks go unanswered.
PAMOJA_LORAWAN_RELAY_ENABLED: Always send through a relay.
PAMOJA_LORAWAN_RELAY_INITIALIZED: The device knows nothing of a relay, TS011-1.0.1 section 3.9.
PAMOJA_LORAWAN_RELAY_SYNCHRONIZED: It knows when the relay next scans.
PAMOJA_LORAWAN_RELAY_UNSYNCHRONIZED: It knows how a relay scans, but not when.
PAMOJA_LORAWAN_SAVED_LEN: How many bytes a saved device state takes.
PAMOJA_LORAWAN_STATE_CORRUPT: A saved state that is corrupt.
PAMOJA_LORAWAN_STATE_FORMAT: A saved state in a format this build does not read, format.
PAMOJA_LORAWAN_STATE_LENGTH: A saved state of the wrong length.
PAMOJA_LORAWAN_STATE_PLAN: A saved state from another channel plan.
PAMOJA_LORAWAN_WINDOW_RX1: The first receive window, on the uplink’s downlink channel.
PAMOJA_LORAWAN_WINDOW_RX2: The second receive window, on the fixed frequency and data rate.
PAMOJA_LORAWAN_WINDOW_RXR: The relay window, which a device under a relay opens last, TS011-1.0.1 chapter 7.
PAMOJA_LORAWAN_WOR_NEXT_UPLINK: The uplink goes out at the time the exchange named.
PAMOJA_LORAWAN_WOR_NEXT_WAKE_UP: The relay is woken again first, as the network’s BackOff asks.

Functions§

pamoja_lorawan_device_settings^⚠: Fills in the settings of a typical node with a radio’s output power range.
pamoja_lorawan_end_device_channel^⚠: Reads one of the channels a device may send on.
pamoja_lorawan_end_device_error^⚠: Reads why a device’s last call failed.
pamoja_lorawan_end_device_free^⚠: Releases a device handle.
pamoja_lorawan_end_device_heard^⚠: Reads a frame heard in one of the receive windows of the last transmission, without saying which.
pamoja_lorawan_end_device_heard_in^⚠: Reads a frame heard in a given receive window of the last transmission.
pamoja_lorawan_end_device_heard_wor_ack^⚠: Reads the acknowledgment a relay answered the last wake-on-radio frame with.
pamoja_lorawan_end_device_join^⚠: Builds a join request.
pamoja_lorawan_end_device_new^⚠: Makes a device that joins over the air.
pamoja_lorawan_end_device_no_wor_ack^⚠: Says what to do once the acknowledgment window closed with nothing in it.
pamoja_lorawan_end_device_nothing_heard^⚠: Says what comes next once both receive windows closed with nothing for the device.
pamoja_lorawan_end_device_personalized^⚠: Makes a device activated by personalization, with its session provisioned.
pamoja_lorawan_end_device_relay_mode^⚠: Reports how a device uses a relay, TS011-1.0.1 sections 3.9 and 10.2.
pamoja_lorawan_end_device_relay_status^⚠: Returns what the relay’s last acknowledgment said about itself, TS011-1.0.1 table 14.
pamoja_lorawan_end_device_repeat^⚠: Sends the last uplink again, the same frame on a channel chosen afresh.
pamoja_lorawan_end_device_request_device_time^⚠: Asks the network, with the next uplink, for the time.
pamoja_lorawan_end_device_request_link_check^⚠: Asks the network, with the next uplink, how well it hears the device.
pamoja_lorawan_end_device_resume^⚠: Puts a saved state back on a device made on the same channel plan.
pamoja_lorawan_end_device_save^⚠: Saves a joined device’s state, to keep across a loss of power.
pamoja_lorawan_end_device_send^⚠: Builds an uplink carrying a payload.
pamoja_lorawan_end_device_send_empty^⚠: Builds an uplink with no payload, carrying the answers the device owes, an acknowledgment, or an ADR acknowledgment request.
pamoja_lorawan_end_device_set_battery^⚠: Sets what the device reports its battery as, when a network asks.
pamoja_lorawan_end_device_status^⚠: Reads where a device stands.
pamoja_lorawan_end_device_use_relay^⚠: Turns relay mode on or off, TS011-1.0.1 section 10.2 and appendix 5.