LoRaWAN class module and subsystem

1. LoRaWAN Class Module
& Subsystem
for LoRa devices
Jian-Hong Pan (StarNight)
@ Netdev 0x12 Conf 2018

2. Outline
● History
○ Scientific farmers
● LoRa Hardware
● IEEE 802.15.4
○ Topology
○ Comparison
○ IEEE 802.15.4 MAC
over LoRa PHY
● LoRaWAN
○ Class A, B and C
○ Frame
○ Keys and Activation
● LoRa/LoRaWAN
subsystem
○ Class Module
○ Fakelr

3. Who am I
潘建宏 / Jian-Hong Pan (StarNight)
I come from Taiwan !
Work in Endless Mobile now.
You can find me at ～
http://www.slideshare.net/chienhungpan/
GitHub : starnight
Email : starnight [AT] g.ncu.edu.tw

4. Map: https://upload.wikimedia.org/wikipedia/commons/0/06/Taiwan_ROC_political_division_map.svg
Taiwan
Formosa
Main island area:
~35,980km2
Grow good
grains,
vegetables,
fruits, flowers,
trees ...

5. History
● The Physics of the IoT
○ by David Mikolas @ Taipei.py 2016.06.30
○ https://www.youtube.com/watch?v=iVlXt6RbgCE#t=18m30s
● 科技農夫陳幸延──農田裡的開源自造者
○ The Scientific Farmer, Yan -- A Maker in the Farm
○ by 顏理謙, BUSINESS NEXT - 2016.06.10
● Location Aware Sensing System (LASS)
○ LASS環境感測網路系統 http://lass-net.org/
● 【科技農夫共創微氣候新農耕模式】年輕小農靠開源翻轉傳
統農業
○ [Scientific farmers creates the new farming methods and utensils] Young
farmers strengthen traditional agriculture with Open Source
○ by 何維涓, iThome - 2017.08.19

6. Wireless Technology
● Features
○ Long distance (coverage)
○ Short data message
○ Power consumption issue
● Low-Rate Wireless Personal
Area Networks (LR-WPANs)
○ IEEE 802.15.4
● Low-Power Wide-Area
Network (LPWAN)
○ LoRa
○ Ultra Narrow Band:
■ Sigfox, NB-IoT ...
Gateway
or Edge
Internet
End-Device
End-Device
End-Device
Outdoor
Wireless
measurement / control

7. From LPWAN - The Benefits of LPWAN Technology vs Other IoT Connectivity Options,
written by Calum McClelland on iotforall.com
Bandwidth - Range of Wireless
LoRa

8. Low Power
Long RangeHigh Speed
Bargain
LPWAN

9. LoRa
LoRa is the physical (PHY) layer or the wireless modulation
utilized to create the long range communication link.
● Chirp spread spectrum (CSS) radio modulation
● Good link budget
● Low data rate
● Could be quite low power consumption
● Radio frequency should be used
according to regional laws
Reference: LoRaWAN™ 101 – A Technical Introduction by LoRa Alliance - November, 2015
What is LoRa? by LINK LABS - February 14, 2015

10. Link Budget
dbm
TX Power
RX Power
TX Antenna
RX Antenna
Connector
Connector
Free Space
distance

11. LoRa Physical Message Formats
Preamble PHDR PHDR_CRC PHYPayload CRC
Preamble PHDR PHDR_CRC PHYPayload
Uplink Message:
Downlink Message:
Preamble, PHDR, PHDR_CRC and CRC are inserted by the
radio transceiver
Reference: LoRaWAN™ Specification V1.0.2 by LoRa Alliance - July, 2016, P.11

12. IEEE 802.15.4
IEEE 802.15.4 is a technical standard which defines the
operation of low-rate wireless personal area networks
(LR-WPANs). It specifies the physical (PHY) layer and media
access control (MAC) for LR-WPANs.
Reference: Wikipedia IEEE 802.15.4 https://en.wikipedia.org/wiki/IEEE_802.15.4
Cluster tree networkStar topology Peer to peer topology
PAN Coordinator Full-Function Device (FFD) Reduced-Function Device (RFD)

13. Comparison
LoRaWAN
Star
Topology
LoRa
Good Link
Budget
IEEE 802.15.4
MAC
Cluster Tree
Network
IEEE 802.15.4
PHY
Normal Link
Budget
Application
Presentation
Session
Transport
Network
MAC Layer
PHY Layer
LR-WPAN LPWAN

14. Combine Both Advantages
Application
Presentation
Session
Transport
Network
MAC Layer IEEE 802.15.4 MAC Cluster Tree Network
PHY Layer LoRa Good Link Budget
TCP/UDP
6LoWPAN
Socket APIs
LoRa acts as an IEEE 802.15.4 PHY

15. Cluster Tree Network &
Good Link Budget
Internet
PAN Coordinator
Full-Function Device (FFD)
Reduced-Function Device (FFD)
LoRa
Each node can have a IPv6
address, if it has 6LoWPAN

16. LoRa
Transceiver
Hardware
SX127X
SPI
Main Board
Raspberry Pi
SPI_CE1
SPI BUS
LoRa
Transceiver
SX127X
SPI
Main Board
Raspberry Pi
SPI_CE1
SPI BUS

17. One of LoRa Transceiver
Semtech - SX1276/77/78/79 for example
http://www.semtech.com/images/datasheet/sx1276.pdf
● 168 dB maximum link budget
● High sensitivity: down to -148 dBm
● LoRa and FSK/OOK mode
● SPI interface
Part Number Frequency Range Spreading Factor Bandwidth Effective Bitrate Est. Sensitivity
SX1276 137 - 1020 MHz 6 - 12 7.8 - 500 kHz .018 - 37.5 kbps -111 to -148 dBm
SX1277 137 - 1020 MHz 6 - 9 7.8 - 500 kHz .011 - 37.5 kbps -111 to -139 dBm
SX1278 137 - 525 MHz 6 - 12 7.8 - 500 kHz .018 - 37.5 kbps -111 to -148 dBm
SX1279 137 - 960MHz 6 - 12 7.8 - 500 kHz .018 - 37.5 kbps -111 to -148 dBm

19. Let's Have an IEEE 802.15.4 over LoRa
Linux Device Driver for IoT
https://www.slideshare.net/chienhungpan/lets-have-an-ieee-8
02154-over-lora-linux-device-driver-for-iot

20. However,
the IEEE 802.15.4 over LoRa PHY
cannot communicate with
orginal IEEE 802.15.4 devices.
They have different PHY layers.

21. So, how about
a new class module/subsystem
for the LoRa devices.
https://marc.info/?l=linux-wpan&m=150642102001917&w=2

22. LoRaWAN (V1.0.2)
LoRaWAN is a media access control (MAC) layer protocol for
managing communication between LPWAN gateways and
end-node devices, maintained by the LoRa Alliance.
● Star topology
● Uplink - Downlink
● Over LoRa or FSK
Reference: Wikipedia LPWAN https://en.wikipedia.org/wiki/LPWAN
LoRaWAN™ Specification V1.0.2 by LoRa Alliance - July, 2016, P.12
● Classes
○ Class A: Base line, ALOHA
○ Class B: Beacon
○ Class C: Continuous

23. RECEIVE_DELAY2 / JOIN_ACCEPT_DELAY2
Node #N
Node #2
Node #1
Gateway /
Forwarder
(s)
Network
Server
...
LoRa or FSK
Ethernet, WiFi,
3/4/5G ...
Transmit time on air
RECEIVE_DELAY1 /
JOIN_ACCEPT_DELAY1
RX1 RX2Transmit

24. US902-928 Default Settings
The following parameters are recommended values for the
US902-928 band.
● RECEIVE_DELAY1 1s
● RECEIVE_DELAY2 2s
- (must be RECEIVE_DELAY1 + 1s)
● JOIN_ACCEPT_DELAY1 5s
● JOIN_ACCEPT_DELAY2 6s
Reference: LoRaWAN™ 1.0.2 Regional Parameters by LoRa Alliance - Feb, 2017 rb, P.17

25. DataRate Configuration Indicative physical bit rate [bit/sec]
0 LoRa: SF10 / 125 kHz 980
1 LoRa: SF9 / 125 kHz 1760
2 LoRa: SF8 / 125 kHz 3125
3 LoRa: SF7 / 125 kHz 5470
4 LoRa: SF8 / 500 kHz 12500
5:7 RFU
8 LoRa: SF12 / 500 kHz 980
9 LoRa: SF11 / 500 kHz 1760
10 LoRa: SF10 / 500 kHz 3900
11 LoRa: SF9 / 500 kHz 7000
12 LoRa: SF8 / 500 kHz 12500
13 LoRa: SF7 / 500 kHz 21900
14:15 RFU
Reference: Table 11: TX Data rate table
LoRaWAN™ 1.0.2 Regional Parameters by LoRa Alliance - Feb, 2017 rb, P.14
LoRa CHIRP introduction

26. MAC Data Message Format
(End-device <-> Gateway)
Reference: Figure 9: LoRa message format elements
LoRaWAN™ Specification V1.0.2 by LoRa Alliance - July, 2016, P.14

27. US902-928 Maximum payload size
Data Rate M N
0 19 11
1 61 53
2 133 125
3 250 242
4 250 242
5:7 Not defined
8 41 33
9 117 109
10 230 222
11 230 222
12 230 222
13 230 222
14:15 Not defined
Reference: Table 14: US902-928 maximum payload size (repeater compatible),
LoRaWAN™ 1.0.2 Regional Parameters by LoRa Alliance - Feb, 2017 rb, P.16

28. MHDR - MAC Header
7…5 bits 4…2 bits 1…0 bits
MType RFU Major
MType Description
000 Join Request
001 Join Accept
010 Unconfirmed Data Up
011 Unconfirmed Data Down
100 Confirmed Data Up
101 Confirmed Data Down
110 RFU
111 Proprietary
Major bits Description
00 LoRaWAN R1
Reference: Table 1: MAC message types and Table 2: Major list,
LoRaWAN™ Specification V1.0.2 by LoRa Alliance - July, 2016, P.15

29. FHDR - Frame Header
● For Uplink Frames
● For Downlink Frames
7 bit 6 bit 5 bit 4 bit 3 … 0 bits
ADR ADRACKReq ACK RFU FOptsLen
7 bit 6 bit 5 bit 4 bit 3 … 0 bits
ADR RFU ACK FPending FOptsLen
4 bytes 1 byte 2 bytes 0 … 15 bytes
DevAddr FCtrl FCnt FOpts
Reference: 4.3.1 Frame header (FHDR),
LoRaWAN™ Specification V1.0.2 by LoRa Alliance - July, 2016, P.16

30. FCnt - Frame Counter
● Each end-device has two frame counters:
○ FCntUp: uplink to the network server and incremented by the end-device
○ FCntDown: downlink from the network server and incremented by the
network server.
● The network server tracks the uplink frame counter and generates the
downlink counter for each end-device.
● After a JoinReq – JoinAccept message exchange or a reset for a
personalized end-device, both frame counters are reset to 0.
● The FCnt is not incremented in case of multiple transmissions of an
unconfirmed frame, or a confirmed frame that is not acknowledged.
● The end-device shall not reuse the same FCntUp value, except for
retransmission, with the same application and network session keys.
Reference: 4.3.2 Frame Counter (FCnt),
LoRaWAN™ Specification V1.0.2 by LoRa Alliance - July, 2016, P.18

31. FPort - Port Field
If the frame payload field is not empty, the port field must be
present.
● 0 for FRMPayload contains MAC commands only.
● 1…223 (0x01…0xDF) for application-specific.
● 224 is dedicated to LoRaWAN Mac layer test protocol.
● 225…255 (0xE1…0xFF) are reserved for future standardized application
extensions.
Reference: 4.3.2 Port Field (FPort),
LoRaWAN™ Specification V1.0.2 by LoRa Alliance - July, 2016, P.19

32. MAC Command
A single data frame can contain any sequence of MAC
commands in 2 ways
1. Piggybacked in the FOpts field
a. Piggybacked MAC commands are always sent without encryption
b. Must not exceed 15 octets
2. Sent as a separate data frame, in the FRMPayload field with the FPort field
being set to 0
a. MAC commands sent as FRMPayload are always encrypted
b. Must not exceed the maximum FRMPayload length
3. More details could be found in Chapter 5 of LoRaWAN™ Specification V1.0.2
Reference: 5 MAC Commands,
LoRaWAN™ Specification V1.0.2 by LoRa Alliance - July, 2016, P.22

33. 3 AES-128 Keys
● AppKey - Application key
○ The AppKey is an AES-128 root key specific to the end-device.
○ Used for Over-the-Air Activation
○ Used to derive the session keys NwkSKey and AppSKey specific for
that end-device if it is activated by Over-the-Air.
● NwkSKey - Network session key
○ Used to calculate and verify the MIC (message integrity code) of all data
messages to ensure data integrity.
○ Used to encrypt and decrypt the frame payload field of a MAC data
messages if FPort is 0.
● AppSKey - Application session key
○ Used to encrypt and decrypt the frame payload field of a MAC data
messages if FPort is 1 ~ 255.

34. Activation
1. by Over-the-Air (Join Procedure)
a. Both end device and network server know and store AppKey directly.
b. End device sends a Join-Request Message in plain text containing
AppEUI and DevEUI to network server.
c. Network server receives the Join-Request Message and responds a
corresponding Join-Accept Message containing NetID and DevAddr.
Join-Accept Message is encrypted by AppKey.
d. Both end device and network server derive NwkSKey and AppSKey
respectively with AppKey, NetID and some other fields exchanged in
Join-Request and Join-Accept messages.
2. by Personalization (Skip Over-the-Air Procedure)
a. End device and network server already know and store DevAddr,
NwkSKey and AppSKey directly.
Reference: 6 End-Device Activation,
LoRaWAN™ Specification V1.0.2 by LoRa Alliance - July, 2016, P.32 ~ 36

35. Activation Over-the-Air
Node
Gateway /
Forwarder
(s)
Network
Server
AppKey AppKey
1. Join Request: AppEUI, DevEUI
2. Join Accept encrypted with AppKey:
…, NetID, DevAddr, …
3. derive
AppSKey,
NwkSKey
3. derive
AppSKey,
NwkSKey

36. Over-the-Air Activation
Join Request Message
Join Accept Message

37. SX127X
LoRa/LoRaWAN subsystem
fakelr
LoRaWAN class module
socket API
(AF_LORAWAN, PF_LORAWAN ...)
…
Utilities:
Activation, settings
Specific applications
Device drivers
Act as a network device
Applications
LoRa device interface

38. LoRaWAN Class Module
(draft)
https://github.com/starnight/LoRa/blob/lorawan-ndo/LoRaWAN/
It is a temporary URL and will be moved in the future
Focus on LoRaWAN v1.0.2 class A device first

39. Act as a Network Device (socket.c)
● static struct proto lrw_dgram_prot;
● static const struct proto_ops lrw_dgram_ops {
.family = PF_LORAWAN,
... };
● static const struct net_proto_family lorawan_family_ops {
.family = PF_LORAWAN,
... };
● static struct packet_type lorawan_packet_type {
.type = htons(ETH_P_LORAWAN),
... };
● proto_register(&lrw_dgram_prot, 1);
● sock_register(&lorawan_family_ops);
● dev_add_pack(&lorawan_packet_type);

40. LoRa Device Interface (lora.h)
struct lora_hw {
struct device *parent;
void *priv;
u32 channels;
u8 current_channel;
s32 *tx_powers;
size_t tx_powers_size;
s32 transmit_power;
};
struct lora_hw *
lora_alloc_hw(size_t, struct lora_operations *);
void lora_free_hw(struct lora_hw *);
int lora_register_hw(struct lora_hw *);
void lora_unregister_hw(struct lora_hw *);
void lora_rx_irqsave(struct lora_hw *,
struct sk_buff *);
void lora_xmit_complete(struct lora_hw *,
struct sk_buff *);
struct lora_operations {
int (*start)(struct lora_hw *);
void (*stop)(struct lora_hw *);
int (*xmit_async)(struct lora_hw *,
struct sk_buff *);
int (*set_txpower)(struct lora_hw *, s32);
int (*set_frq)(struct lora_hw *, u32);
int (*set_bw)(struct lora_hw *, u32);
int (*set_mod)(struct lora_hw *, u8);
int (*set_sf)(struct lora_hw *, u8);
int (*start_rx_window)(struct lora_hw *, u32);
/* Set & get the state of the LoRa device. */
int (*set_state)(struct lora_hw *, u8);
int (*get_state)(struct lora_hw *, u8);
};

41. Private Structures (lorawan.h)
struct lrw_struct {
struct device dev;
struct lora_hw hw;
struct lora_operations *ops;
struct sk_buff_head rx_skb_list;
struct list_head ss_list;
struct mutex ss_list_lock;
struct lrw_session *_cur_ss;
bool rx_should_ack;
uint8_t role;
u8 state;
__le64 app_eui, dev_eui;
__le32 devaddr;
u8 appkey[LORA_KEY_LEN];
u8 nwkskey[LORA_KEY_LEN];
u8 appskey[LORA_KEY_LEN];
...
u16 fcnt_up, fcnt_down;
struct tasklet_struct xmit_task;
struct work_struct rx_work;
struct net_device *ndev;
possible_net_t _net;
};
struct lrw_session {
struct lrw_struct *lrw_st;
struct list_head entry;
u8 devaddr[LRW_DEVADDR_LEN];
u16 fcnt_up;
u16 fcnt_down;
u8 fport;
struct sk_buff *tx_skb;
struct sk_buff *rx_skb;
…
u8 state;
spinlock_t state_lock;
struct timer_list timer;
struct work_struct timeout_work;
u16 rx_delay1;
u16 rx_delay2;
u16 rx1_window;
u16 rx2_window;
u16 ack_timeout;
};

42. enum {
LRW_INIT_SS,
LRW_XMITTING_SS,
LRW_XMITTED,
LRW_RX1_SS,
LRW_RX2_SS,
LRW_RXTIMEOUT_SS,
LRW_RXRECEIVED_SS,
LRW_RETRANSMIT_SS,
};
struct lrw_session {
…
u8 state;
…
};
Receive Slot Timing State Machine
INIT_SS
XMITTING_SS
XMITTED
RX2_SS
RX1_SS
RXTIMEOUT_SS
RXRECEIVED_SS
RETRANSMIT_SS
lrw_rx_work
lora_rx_irqsave
lrw_if_start_xmit

43. Crypto (lrwsec.h)
struct crypto_shash *lrw_mic_key_setup(u8 *k, size_t k_len);
int lrw_calc_mic(struct crypto_shash *tfm,
u8 dir, u8 *devaddr, u32 fcnt, u8* buf, size_t len, u8 *mic4);
void lrw_mic_key_free(struct crypto_shash *tfm);
struct crypto_skcipher *lrw_encrypt_key_setup(u8 *k, size_t k_len);
int lrw_encrypt_buf(struct crypto_skcipher *tfm,
u8 dir, u8 *devaddr, u32 fcnt, u8 *buf, size_t len);
int lrw_decrypt_buf(struct crypto_skcipher *tfm,
u8 dir, u8 *devaddr, u32 fcnt, u8 *buf, size_t len);
void lrw_encrypt_key_free(struct crypto_skcipher *tfm);

44. LoRaWAN ToDo:
1. Activation
2. Configurations:
a. Regional Parameters
b. IOCTL
i. Region
ii. Channel
iii. Data Rate
iv. TX Power
3. MAC Commands
4. Documentation
5. User space utilities:
a. Config
b. Activation
i. Over the Air
ii. Personalization
6. Connect to network
server via a gateway
…

45. Fakelr Driver (draft)
● It is a simple dummy LoRa device driver for LoRaWAN
class module
● Used for verifying of LoRaWAN class module
● As a template
https://github.com/starnight/LoRa/tree/lorawan-ndo/LoRa
It is a temporary URL and will be moved in the future
Hope there will be more real LoRa device drivers in the future

46. Other LoRa Device Drivers
● The patch set “[RFC net-next 00/15] net: A socket API for
LoRa” by Andreas Färber
https://lkml.org/lkml/2018/7/1/67
● The compatibility between LoRaWAN class module and
LoRa device drivers is important

47. Test with rpi-4.16.y on Raspberry Pi
[zack@starnight linux-rpi]$ git status
On branch rpi-4.16.y-lorawan
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)
modified: arch/arm64/Makefile
modified: drivers/net/Kconfig
modified: drivers/net/Makefile
modified: include/linux/socket.h
modified: include/uapi/linux/if_arp.h
modified: include/uapi/linux/if_ether.h
modified: net/Kconfig
modified: net/Makefile
modified: net/core/dev.c
Untracked files:
(use "git add <file>..." to include in what will be committed)
drivers/net/lorawan/
include/linux/lora.h
net/lorawan/

49. Reference
● LoRa Chirp
● LoRaWAN™ What is it?
● LoRaWAN™ Specification V1.0.2 from LoRa™ Alliance
● Wikipedia - LPWAN
● Semtech SX1276/77/78/79 datasheet
● IEEE Std 802.15.4-2015 from IEEE
● Linux IEEE 802.15.4 Documentation
● Loopback IEEE 802.15.4 interface: fakelb.c
● Enabling firmware updates over LWPAN - Arm TechCon
2017