View source for DTLS on SAM R21 Xplained Pro: Guide/Demo

== Summary == 
This article supplies the instructions to setup a DTLS connection by using RIOT-OS and the WolfSSL DTLS example provided by RIOT-OS. The first part guides the user in setting up two SAM R21 Xplained Pro microcontrollers using the example application and establish a connection between them using DTLS and RIOTs generic networking stack. The second part guides the user in setting up virtual native boards in RIOT and establish a DTLS-based connection between them. This is done to make capturing the DTLS packets possible via Wireshark.

== Requirements ==

You must have followed the [[Riot-OS Setup]] step 1, 2 and 3 before using this guide. It is assumed that RIOT-OS is installed to ~/RIOT/.

* Operating system: Ubuntu 24.04 (Note: This guide was created running Ubuntu as a Virtual Machine on Oracle VirtualBox 6.1)
* Packages: git python3

== Description ==

=== Step 1 ===
This step is an addition to the [[Riot-OS Setup]]. 

* Update your packages if you have not already done so.
 sudo apt-get update
* Install the pyudev package
 sudo apt-get install python3-pyudev 
* Find out the serial numbers of your SAM R21 XPro devices and note them for later use
 make list-ttys
* Open two additional terminals and connect to both devices by using their ttys. Adjust the code if your ttys differ.
 cd RIOT/dist/tools/pyterm
 ./pyterm -p /dev/ttyACM0
 ./pyterm -p /dev/ttyACM1

=== Step 2 ===
Build the application and flash it onto both devices.

* Navigate to the folder containing the WolfSSL DTLS example in RIOT and build the application
 cd RIOT/examples/dtls-wolfssl
 make BOARD=samr21-xpro
* Flash the newly built application onto both devices using their serial numbers 
 make BOARD=samr21-xpro SERIAL="ATML21270318xxxxxxx" flash
 make BOARD=samr21-xpro SERIAL="ATML21270318xxxxxxx" flash
* The example application is now running on both devices. Use command ''help'' to show the available options

[[File:DTLS-WolfSSL-Help.png|thumb|none|750px|WolfSSL DTLS Example Help Menu]]
 
=== Step 3 ===
Use the applications to setup a DTLS connection 

* Use ''ifconfig'' on the device that is designated as the server and note the IPv6 address
* Start the DTLS Server
 dtlss
* Use the DTLS Client to start the connection test
 dtlsc IPv6-server-address

[[File:WolfDTLS-Connection.png|thumb|none|750px|WolfSSL DTLS Example Connection]]

== Capturing DTLS Traffic ==
If you want to capture and analyze the DTLS the packets using a packet sniffer, e.g. Wireshark, you have to use RIOT native boards, since SAM R21 XPro devices are not powerful enough to support packet capture with Wireshark on their own.

=== Wireshark Setup ===
Follow the steps to install Wireshark on Ubuntu 24.04, if necessary:
* Install Wireshark
 sudo apt install wireshark
* When asked if non-superusers should be able to catpure packets answer "Yes".
* Add your user to the wireshark group to make capture possible
 sudo usermod -a -G wireshark "$USER"
* Check if the wireshark group is present for your user
 groups $USER
* Log out and log in or restart your system to apply the change.

=== Step 1 ===
Setup a virtual network for RIOT instances by using the ''Tapsetup''-tool.
* Navigate to the ''Tapsetup''-tool and create two virtual network taps and a virtual bridge
 cd ~
 cd RIOT/dist/tools/tapsetup
 sudo ./tapsetup --create 2
* Build dtls-wolfdtls for RIOT native boards
 cd ~
 cd RIOT/examples/dtls-wolfssl
 make all
* Setup the first virtual RIOT board
 PORT=tap0 make term
* Setup the second virtual RIOT board using a second terminal
 cd RIOT/examples/dtls-wolfssl
 PORT=tap1 make term

=== Step 2 ===
Configure Wireshark to capture packets on either tap0, tap1 or tapbr0 (Bridge). This depends on which view is more interesting to you. In the following steps tap1 is used for capturing packets since the DTLS server is run on this Tap.
* Start Wireshark and set it to capture packets on the interface tap1
* Use the applications to setup a DTLS connection. First use ''ifconfig'' on one of the native boards. Note the IPv6 address and then use the following command to start the DTLS server:
 dtlss
* Use this command on the other native board using the address noted previously:
 dtlsc IPv6-server-address
* You should receive confirmation of a successful connection.

=== Step 3 ===
Analyze the captured traffic in Wireshark

[[File:WolfDTLS-Wireshark-Capture.png|thumb|none|750px|WolfSSL DTLS Example Wireshark Capture]]
 
== Used Hardware ==

* 2x [[Atmel SAM R21 Xplained Pro]]
* Connective cables (Micro USB B)

== Courses ==

* [[Riot-OS Setup]]

== References ==

* https://www.riot-os.org/
* https://www.wolfssl.com/

[[Category:Documentation]]