View source for Raspberry Pi 3B+ 802.15.4/6LoWPAN Setup

== Summary == 

Information on how to setup a Raspberry Pi 3B+ for 802.15.4 radio/6LoWPAN communication by utilizing an Openlabs 802.15.4 radio module.

'''This was tested successfully with Raspbian 10 (Buster) and Raspbian 11 (Bullseye).''' I assume it is also working on the latest Raspbian 12 (Bookworm).

== Requirements ==

* ([[Raspberry_Pi_3,_Model_B%2B,_WLAN,_BT|Raspberry Pi 3B+]])
* Operating system: Raspberry Pi OS (Raspbian)
* Openlabs 802.15.4 radio module: https://openlabs.co/store/Raspberry-Pi-802.15.4-radio
* Optional/alternatively (not tested yet): [[Raspberry_Pi_6LoWPAN_SLIP_radio_module|Raspberry Pi 6LoWPAN SLIP radio module]]

== Setup/Config 802.15.4/6LoWPAN on a Raspberry ==

=== Install Raspbian on Raspberry Pi 3B+ ===

* Use Raspberry Pi Imager
* Optional: Download Raspbian/Raspberry Pi OS from https://www.raspberrypi.com/software/operating-systems/

=== Preparation of Raspbian ===

Access the Raspberry Pi by attaching it via HDMI to a monitor. After enabling SSH it is possible to connect via SSH/terminal (default credentials are pi:raspberry).

* (Optionally) Change keyboard setting to "German" and reboot:

 sudo dpkg-reconfigure keyboard-configuration

* Activate and start SSH on Raspberry:

 sudo systemctl start ssh
 sudo systemctl enable ssh

* Upgrade of Raspbian:

 sudo apt update && sudo apt upgrade

=== Enable support for IEEE 802.15.4/LoWPAN devices ===

* Plug the OpenLabs 802.15.4 radio module directly onto pins 15-26 of the Raspberry's P1 header (in the middle):

[[File:Raspberry-pi-802.15.4-radio_module.jpg|220px]][[File:Raspberry-pi-802.15.4-radio_connected.jpg|370px]]

* There is an existing overlay for this transceiver shipped with Raspbian, should be in <code>/boot/overlays/at86rf233-overlay.dtb</code> or <code>/boot/overlays/at86rf233.dtbo</code>:

 ls /boot/overlays/at86rf233.dtbo

* Enable transceiver by modifying the <code>/boot/config.txt</code> file and reboot:

=== Installation of Linux WPAN tools ===

'''Sources/Links: see References:[[#Linux WPAN tools]]'''

* First install <code>git</code> and clone the wpan-tools Repository:

 sudo apt install git
 sudo mkdir /opt/src
 sudo chown pi /opt/src
 cd /opt/src
 git clone https://github.com/linux-wpan/wpan-tools

* Install some required packages before building the wpan-tools:

 sudo apt install dh-autoreconf libnl-3-dev libnl-genl-3-dev

* Configure, build and install wpan-tools:

 cd /opt/src/wpan-tools
 ./autogen.sh
 ./configure CFLAGS='-g -O0' --prefix=/usr --sysconfdir=/etc --libdir=/usr/lib
 make
 sudo make install

* Verification/test of wpan-tools installation:

 iwpan dev

=== MANUAL WPAN interface configuration ===

'''Sources/Links: see References:[[#WPAN interface configuration]]'''

* Configure the default PAN ID of RIOT-OS/SAMR21-xpro: <code>0x23</code>
* Configure the default channel ID of RIOT-OS/SAMR21-xpro: <code>26</code>

 ip link set lowpan0 down
 ip link set wpan0 down
 iwpan phy phy0 set channel 0 26 # same network ID and channel as RIOT default
 iwpan dev wpan0 set pan_id 0x23 # same network ID and channel as RIOT default
 ip link add link wpan0 name lowpan0 type lowpan
 ip link set wpan0 up
 ip link set lowpan0 up

* Afterwards the <code>lowpan0</code> interface on Raspberry has a link-local IPv6 address:

 root@raspberrypi:~# ip a
 1: lo: [...]
 2: eth0: [...]
 3: wlan0: [...]
 4: wpan0: <BROADCAST,NOARP,UP,LOWER_UP> mtu 123 qdisc pfifo_fast state UNKNOWN group default qlen 300
    link/ieee802.15.4 36:3a:07:cc:65:41:2b:31 brd ff:ff:ff:ff:ff:ff:ff:ff
 5: lowpan0@wpan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1280 qdisc noqueue state UNKNOWN group default qlen 1000
    link/6lowpan 36:3a:07:cc:65:41:2b:31 brd ff:ff:ff:ff:ff:ff:ff:ff
    inet6 fe80::343a:7cc:6541:2b31/64 scope link
       valid_lft forever preferred_lft forever

'''NOTE/CAUTION: Every reboot changes the link-local IPv6 address of the <code>lowpan0</code> interface on the Raspberry!'''

See [[#PERSISTENT wpan0 and lowpan0 configuration]] to configure a persistent link-local address.

There are also scripts available to create/delete a lowpan interface (or to create/delete a monitor interface): https://github.com/RIOT-Makers/wpan-raspbian

=== PERSISTENT wpan0 and lowpan0 configuration ===

With static long hardware address and static link-local IPv6 address (to avoid a random link-local IPv6 address on each reboot).

'''Sources/Links: see References:[[#Persistent WPAN interface configuration]]'''

* Clone riot-makers/wpan-raspbian GitHub repo:

 cd /opt/src
 git clone https://github.com/riot-makers/wpan-raspbian
 cd wpan-raspbian

* Copy some helper (shell) scripts to a well-known location:

 sudo cp -r usr/local/sbin/* /usr/local/sbin/.
 sudo chmod +x /usr/local/sbin/*

* Afterwards copy files for systemd integration:

 sudo cp etc/default/lowpan /etc/default/.
 sudo cp etc/systemd/system/lowpan.service /etc/systemd/system/.

* Modify 802.15.4 channel ID and PAN ID in <code>/etc/default/lowpan</code> as needed:

 sudo nano /etc/default/lowpan
 CHN="13"
 PAN="0xbeef"
 # set MAC to "" for random mac/hw address
 MAC="02:0:0:0:0:0:0:1"
 # set IPv6 to "" if not required; note: set a prefix length
 #IP6="fdaa:bb:cc:dd::1/64"
 # Set ACK requests (Only enable if all devices on your PAN support ACKs)
 ACKREQ=0

Note: <code>MAC="02:0:0:0:0:0:0:1"</code> was taken from https://jan.newmarch.name/IoT/LinuxJournal/Routing/, this results in a link-local address of <code>fe80::1</code> for the Raspberry.

* Enable <code>lowpan.service</code> autostart, start 6LoWPAN service and verification:

 sudo systemctl enable lowpan.service
 sudo systemctl start lowpan.service
 ifconfig
 lowpan0: flags=4163<UP,BROADCAST,RUNNING,MULTICAST>  mtu 1280
    inet6 fe80::1  prefixlen 64  scopeid 0x20<link>
    unspec 02-00-00-00-00-00-00-01-00-00-00-00-00-00-00-00  txqueuelen 1000  (UNSPEC)
    RX packets 0  bytes 0 (0.0 B)
    RX errors 0  dropped 0  overruns 0  frame 0
    TX packets 19  bytes 2114 (2.0 KiB)
    TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0
 wpan0: flags=195<UP,BROADCAST,RUNNING,NOARP>  mtu 123
        unspec 02-00-00-00-00-00-00-01-00-00-00-00-00-00-00-00  txqueuelen 300  (UNSPEC)
        RX packets 72  bytes 2016 (1.9 KiB)
        RX errors 0  dropped 0  overruns 0  frame 0
        TX packets 74  bytes 5320 (5.1 KiB)
        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0

== Verification of 6LoWPAN connectivity between a Raspberry and a SAMR21-xpro == 

* Use RIOT's gnrc_networking example and build it for the SAMR21-xpro board, flash the firmware to the SAMR21-xpro and connect via <code>pyterm</code>:

 cd RIOT/examples/gnrc_networking
 make BOARD=samr21-xpro
 make BOARD=samr21-xpro flash
 make BOARD=samr21-xpro term

* Use <code>ifconfig</code> to determine the 802.15.4/6LoWPAN interface ID of SAMR21-xpro (<code>7</code> in this case):

 ifconfig
 # Iface  7  HWaddr: 57:98  Channel: 26  Page: 0  NID: 0x23  PHY: O-QPSK
 [...]
 #           Long HWaddr: E2:F9:02:0F:36:26:A2:68
 [...]
 #           inet6 addr: fe80::e0f9:20f:3626:a268  scope: link  VAL

* Note: All <code>ifconfig</code> config options can be shown with <code>ifconfig <interface id> set</code>.

* RIOT-OS default 802.15.4 channel is 26 and default  PAN ID 0x23. If you change them, make sure to change them in the SAMR21-xpro configuration aswell:
** [optional] Change the channel to 13 and the PAN ID to 0xbeef (see [[RIOT-OS_and_IEEE_802.15.4_/_6LoWPAN|RIOT-OS and IEEE 802.15.4 / 6LoWPAN]] for more information):

 ifconfig 7 set pan_id 0xbeef
 ifconfig 7 set channel 13

=== Ping test from Raspberry to SAMR21-xpro ===

* Multicast ping test through interface <code>lowpan0</code> to group <code>ff02::1</code> (all nodes in the link-local):

 ping ff02::1%lowpan0        
 PING ff02::1%lowpan0(ff02::1%lowpan0) 56 data bytes
 64 bytes from fe80::1%lowpan0: icmp_seq=1 ttl=64 time=0.195 ms
 64 bytes from fe80::e0f9:20f:3626:a268%lowpan0: icmp_seq=1 ttl=64 time=10.4 ms (DUP!)

* Unicast ping (change to link-local IPv6 address of your SAMR21-xpro):

 ping fe80::e0f9:20f:3626:a268%lowpan0
 ping fe80::e0f9:20f:3626:a268%lowpan0
 PING fe80::e0f9:20f:3626:a268%lowpan0(fe80::e0f9:20f:3626:a268%lowpan0) 56 data bytes
 64 bytes from fe80::e0f9:20f:3626:a268%lowpan0: icmp_seq=1 ttl=64 time=23.0 ms
 [...]

=== Ping test from SAMR21-xpro to Raspberry ===

* Multicast ping test through interface 7 to group ff02::1:

 # ping6 ff02::1%7
 # 12 bytes from fe80::1%7: icmp_seq=0 ttl=64 rssi=-61 dBm time=8.309 ms
 # 12 bytes from fe80::1%7: icmp_seq=1 ttl=64 rssi=-61 dBm time=6.124 ms
 # 12 bytes from fe80::1%7: icmp_seq=2 ttl=64 rssi=-59 dBm time=6.461 ms
 #
 # --- ff02::1 PING statistics ---
 # 3 packets transmitted, 3 packets received, 0% packet loss
 # round-trip min/avg/max = 6.124/6.964/8.309 ms

* Unicast ping from SAMR21-xpro to Raspberry 6LoWPAN interface:

 # ping6 fe80::1%7
 # 12 bytes from fe80::1%7: icmp_seq=0 ttl=64 rssi=-61 dBm time=8.467 ms
 # 12 bytes from fe80::1%7: icmp_seq=1 ttl=64 rssi=-61 dBm time=7.966 ms

== Test CoAP communication between Raspberry and SAMR21-xpro ==

* Install <code>python3-pip</code> and <code>aiocoap</code> on Raspberry:

 sudo apt install python3-pip
 pip3 install --upgrade "aiocoap[all]"

* Clone <code>aiocoap</code> repo and start the included simple CoAP server:

 git clone https://github.com/chrysn/aiocoap.git
 cd aiocoap
 python3 server.py

* Use gcoap example on SAMR21-xpro (RIOT-OS repo already cloned):

 cd ~/RIOT/example/gcoap
 make BOARD=samr21-xpro         //build gcoap example
 make BOARD=samr21-xpro flash       //flah gcoap to samr21-xpro
 make BOARD=samr21-xpro term     //start pyterm

* [optional] Reset SAMR21-xpro and change 6LoWPAN settings:

 ifconfig 7 set pan_id 0xbeef
 ifconfig 7 set channel 13

* Send a CoAP request to the CoAP server:

coap put [fe80::1%7] 5683 /send test

== Possible Problems with 6LoWPAN, SAMR21-xpro and Raspberry Pi (with Openlabs 802.15.4 radio) ==

* 6LoWPAN: RIOT does not receive packets from Linux when short_addr is set #11033
** GitHub issue: https://github.com/RIOT-OS/RIOT/issues/11033
** By default this is not set (i.e. in RIOT gnrc_networking example!)
* '''Do not use Raspberry Pi 4 with OpenLabs 802.15.4 radio module:'''
** At least with the newest available Kernel (i.e. 5.10 during our tests) it was '''only possible to send''' 802.15.4 packets to SAMR21-xpro and the Raspberry '''did not receive''' any packets from SAMR21-xpro.
** It is better to use a Raspberry Pi 3B(+)
*** Successfully tested with Raspbian 9 (Stretch), Raspbian 10 (Buster) and Raspbian 11 (Bullseye)
* Monitoring 802.15.4/6LoWPAN traffic: Correct channel ID must be set (RIOT-OS default: 26)
* Communication SAMR21-xpro<->Raspberry: The same channel ID (RIOT-OS default: 26) and PAN ID need to be set (RIOT-OS default: 0x23)

== TODO: Monitoring/Sniffing 802.15.4/6LoWPAN radio with a Raspberry ==

== Used Hardware ==

* [[Raspberry_Pi_3,_Model_B%2B,_WLAN,_BT]]
* https://openlabs.co/store/Raspberry-Pi-802.15.4-radio
* Optional/alternatively (not tested): [[Raspberry_Pi_6LoWPAN_SLIP_radio_module|Raspberry Pi 6LoWPAN SLIP radio module]]
* SAMR21-xpro: [[Atmel_SAM_R21_Xplained_Pro_Evaluation_Platform|Atmel SAM R21 Xplained Pro Evaluation Platform]]

== Courses ==

* IT-Security master's programme: Mobile and Embedded Security ILV

== References ==

* Documentation was (mostly) created based on our CoMatrix project: https://comatrix.eu
* [[Riot-OS_Setup|Wiki: Riot-OS Setup]]
* https://comatrix.eu/setup/raspberry_pi_setup/
* https://openlabs.co/store/Raspberry-Pi-802.15.4-radio
* [[RIOT-OS_and_IEEE_802.15.4_/_6LoWPAN|Wiki: RIOT-OS and IEEE 802.15.4 / 6LoWPAN]]
* Linux WPAN Tools: https://github.com/linux-wpan/wpan-tools
* Python CoAP implementation/library: https://github.com/chrysn/aiocoap

=== Linux WPAN tools ===

* https://github.com/RIOT-OS/RIOT/wiki/How-to-install-6LoWPAN-Linux-Kernel-on-Raspberry-Pi
* https://github.com/RIOT-Makers/wpan-raspbian/wiki/Create-a-generic-Raspbian-image-with-6LoWPAN-support
* https://github.com/RIOT-Makers/wpan-raspbian/wiki/Spice-up-Raspbian-for-the-IoT

=== WPAN interface configuration ===

* https://linux-wpan.org/documentation.html
* https://www.linuxjournal.com/content/low-power-wireless-6lowpan-ieee802154-and-raspberry-pi
* http://morschi.com/2017/04/05/hands-on-riot-6lowpan/

=== Persistent WPAN interface configuration ===

* https://github.com/RIOT-Makers/wpan-raspbian/wiki/Spice-up-Raspbian-for-the-IoT
* https://github.com/RIOT-Makers/wpan-raspbian
* https://jan.newmarch.name/IoT/LinuxJournal/Routing/

[[Category:Documentation]]