# LoRaWAN 1.1

## Message Format

### Radio PHY Layer

* Preamble
  - LoRa modulation: sync word (8 symbols)
    - Public networks: `0x34`
    - Private networks: `0x12`
  - FSK modulation: sync word `0xC194C1` (3 bytes)
* PHDR - physical header (FEC coding rate 4/8)
  - Payload length
  - Payload FEC coding rate (4/5, 4/6, 4/7, 4/8)
  - Payload CRC on/off
* PHDR_CRC - CRC of physical header
* PHYPayload - physical payload
* CRC - physical payload CRC (only in uplink messages)

### LoRaWAN - PHYPayload

* MHDR: MAC header (1 byte)
  - MType: message type and payload format (3 bits)
    - `000` JoinRequest
    - `001` JoinAccept
    - `010` MACPayload - uplink - unconfirmed
    - `011` MACPayload - downlink - unconfirmed
    - `100` MACPayload - uplink - confirmed
    - `101` MACPayload - downlink - confirmed
    - `110` RejoinRequest
    - `111` Proprietary (usually just dropped)
  - Reserved (2 bits)
  - Major: LoRaWAN version (currently `00` - LoRaWAN R1) (2 bits)
* Payload: Payload as indicated by MType (JoinRequest, JoinAccept, MACPayload, RejoinRequest)
* MIC: Message Integrity Code (in JoinAccept the MIC is in the Payload) (4 bytes)
  - Uplink: with DevAddr, FCnt, SNwkSIntKey, FNwkSIntKey, FCnt of confirmed downlink (if Ack), DataRate, Channel
  - Downlink: with DevAddr, FCnt, SNwkSIntKey, FCnt of confirmed uplink (if Ack)

### LoRaWAN - MACPayload

Maximum total length: region-specific

* FHDR:
  * DevAddr (4 bytes)
  * FCtrl (1 byte)
    * ADR (1 bit)
    * ADRACKReq (uplink only; 1 bit)
    * ACK (1 bit)
      - See **Confirmed messages**
    * FPending (downlink only; 1 bit)
      - Device responds with uplink only once
    * ClassB (uplink only; 1 bit)
      - Indicates that device is in Class B mode
    * FOptsLen (4 bits)
  * FCnt (2 bytes)
    - strictly increasing until next JoinAccept
    - FCntUp (incr on each uplink)
    - NFCntDown (LoRaWAN 1.1; incr on each downlink where FPort == 0)
    - AFCntDown (LoRaWAN 1.1; incr on each downlink where FPort != 0)
    - Full width: 32 bits; packet contains 16 lsb
    - FCnt are reset to 0 on JoinAccept; ABP devices never reset
  * FOpts - optional
    - If present, FPort can not be 0
    - If present, MAC commands can not be in payload
    - Encrypted; MIC is calculated after encryption
      - with NwkSEncKey
* FPort - optional
  - Must be present if FRMPayload present
  - FPort 0 means that FRMPayload contains only MAC commands
  - FPort 1..223 is application payload
  - FPort 224 is test protocol
  - Any other FPort should not be transmitted
* FRMPayload - optional
  - Encrypted; MIC is calculated after encryption
    - FPort 0: with NwkSEncKey
    - Other: with AppSKey

### LoRaWAN - JoinRequest

* JoinEUI
* DevEUI
* DevNonce
  - strictly increasing, can only be reset when JoinEUI or NwkKey and AppKey changed
  - device and server keep track of latest

### LoRaWAN - JoinAccept

* JoinNonce
  - strictly increasing, can only be reset when JoinEUI or NwkKey and AppKey changed
  - device and server keep track of latest
* Home_NetID
* DevAddr
* DLSettings
  * OptNeg
    - 0 indicates LoRaWAN 1.0
    - 1 indicates LoRaWAN 1.1 or later
  * RX1DROffset
  * RX2DR
* RxDelay
* CFList (optional)
* CFListType (optional)

### LoRaWAN - RejoinRequest

* DevEUI
* NetID (type 0+2)
* JoinEUI (type 1)
* RJCount0 (type 0+2)
  - strictly increasing until next JoinAccept
* RJCount1 (type 1)
  - strictly increasing, can only be reset when JoinEUI changed

## Beacon Message Format

### Radio PHY Layer

* Preamble
  - LoRa modulation: sync word (8 symbols)
    - Public networks: `0x34`
    - Private networks: `0x12`
  - FSK modulation: sync word `0xC194C1` (3 bytes)
* BCNPayload

### Beacon Frame

* Time - seconds since GPS epoch (4 bytes lsb)
* Time CRC
* InfoDesc
  - 0-2 GPS info, transmitted on antenna N (N=0,1,2)
    - Mulit-antenna gateways transmit different frames on each antenna
  - 3-127 Reserved
  - 128-255 Network-specific
* latitude (3 bytes) + longitude (3 bytes)
  - signed 24 bit

## Device

### Class A

* Random uplink
  - time: random, but not before previous receive windows expired
  - an uplink message is retransmitted until a downlink is received in one of the windows, or max NbTrans times.
    - for confirmed uplink messages, downlink needs Ack set
    - for class B and C, downlink needs to be unicast
  - If more than NbTrans uplink messages are received by the network server, the network server may treat this as a replay attack
  - frequency: random frequency from join/mac-configurable channel list
    - by default: region-specific channel list
* Scheduled downlink windows
  - If network server uses both windows, payload must be identical
  - Device only opens window 2 if no valid downlink in window 1
  - Receive window 1
    - time: join/mac-configurable `receive_delay_1` after uplink ended (±20µs)
      - by default: 1s
    - frequency: function of uplink frequency, region-specific
    - data rate: function of uplink data rate and mac-configuration, region-specific
      - by default: equal to uplink data rate
  - Receive window 2
    - time: join/mac-configurable `receive_delay_2` after uplink ended (±20µs)
      - by default: `receive_delay_1` + 1s
    - frequency: join/mac-configurable
      - by default: region-specific
    - data rate: join/mac-configurable
      - by default: region-specific
* Confirmed messages
  - If a confirmed uplink is received by the network server
    - The network server responds to the message with a downlink that has the Ack bit set in FCtrl
  - If a confirmed downlink is received by a device
    - The device sends the next uplink with the Ack bit set in FCtrl
      - An Ack is only sent once
    - If the network server receives the next uplink without an Ack bit
      - The network server informs the application server
* Adaptive Data Rate (ADR)
  - With ADR the network server controls the data rate and transmission power of a device
  - If ADR is possible, the ADR bit is set in FCtrl
  - If the ADR bit is not set in uplink FCtrl, the network server does not do ADR
  - If the ADR bit is not set in downlink FCtrl, the device can decide what to do
  - Default transmission power: maximum allowed
  - Default data rate:
  - Device behavior:
    - if ADR is applied and data rate or transmission power is optimized
      - on every sent uplink that increments the FCnt, increment `ADR_ACK_CNT`
      - on every received downlink, reset `ADR_ACK_CNT`
      - if `ADR_ACK_CNT` greater than or equal to `ADR_ACK_LIMIT`
        - set the ADRACKReq bit in FCtrl`
      - if `ADR_ACK_CNT` greater than or equal to `ADR_ACK_LIMIT + ADR_ACK_DELAY`
        - step up transmission power until maximum
        - if transmission power equal to maximum
          - step down data rate until minimum
          - if data rate equal to minimum
            - re-enable all default channels

MAC Commands

* Never visible to the application layer or application server
* CID + optional Payload
* Acknowledged in order
* MAC has priority over data payload
* NS must consider max payload size at device DataRate before sending MAC commands

MAC State

* LoRaWAN version
* Device class
* Regional version
* Region/Frequency Plan
* Max EIRP
* Dwell time uplink+downlink on/off
* ADR-DataRate (desired+acked)
* ADR-TxPower (desired+acked)
* `ADR_ACK_LIMIT`, `ADR_ACK_DELAY`
* Channels (desired+acked)
  - on/off
  - frequency
  - data rate range
* RX1 DR Offset (desired+acked)
* RX2 DR (desired+acked)
* RX2 Frequency (desired+acked)
* NbTrans
* RX1 Delay
* Rejoin-counter
* Rejoin-timer

Fixed Device Registration

* LoRaWAN version
* JoinEUI
* DevEUI
* AppKey
* NwkKey + derived JSIntKey and JSEncKey
* AppKey

Activated Device state

* DevAddr
  - Allocated by the network server
* NwkSEncKey, SNwkSIntKey, FNwkSIntKey
* AppSKey
* Previous device state is kept until RekeyInd MAC received

* Counters
* Keys

### Class B

* Extends Class A
* All gateways synchronously transmit "beacons" every `beacon_period` of 128s
  - Every 128s since GPS epoch
  - Account for TBeaconDelay
* The 3.000s before the beacon is `beacon_guard`, no downlink pings can be sent
* The `beacon_window` of 122.880s after the (`beacon_start` + `beacon_reserved` (2.120s)) can be used for downlink pings
* There are 4096 ping slots of 30ms in the `beacon_window`
  - Device gets a pseudo-random slot number in each `beacon_window` - generated from time and DevAddr
* Any gateway can transmit a downlink ping to an end-device in a "ping-slot"

Global state

* Beacon frequency
  - Default: PHY
  - US/CN: Frequency hopping

Device state (additional to Class A)

* Gateways of last uplink
* Ping-slot periodicity (decided by device)
* Ping-slot frequency (decided by network server)
  - Default: PHY
  - US/CN: Frequency hopping
* Ping-slot data rate (decided by network server)

Multicast downlink

* No MAC commands
* Ack=0
* AdrAckReq=0
* MType=unconfirmed down

Beacon

### Class C

* Extends Class A
* Continuously listening on RX2, except during TX or RX1

Device state (additional to Class A)

* Gateways of last uplink

## Network Server

## Application Server

## Join Server