Tutorials IoT

Testing Matter Thread Compliant IoT Devices Using ioter: A Step-by-Step Tutorial

Sangsu Lee

By Sangsu Lee

Samsung’s SmartThings has been working with other leaders in the tech industry to define and develop the Matter protocol, the new industry standard that makes onboarding and control of devices as smooth as possible using an IP-based connection protocol with Wi-Fi, Thread, and Ethernet.

To help OEMs integrate their devices with SmartThings, we have developed ioter to emulate Matter supported Thread devices with a Linux PC and Thread RCP dongle. Additionally, ioter also comes with an automation feature to help you quickly test multiple IoT devices.

What is ioter?

Ioter acts as a device emulator to developers, testers, and manufacturers of connected devices that are compliant with Matter and Thread. Benefits include:

  • Flexibility: Multiple types of IoT devices can be implemented using a single RCP dongle.
  • Multi-Device support: Each RCP dongle supports a single device. ioter supports up to 10 RCP dongles at a time.
  • Low cost: Limited expenses for testing various IoT device types.
  • Time saving: Virtual devices on demand - no need to search for and procure multiple IoT device types.
  • Easy to use: Quickly control the status of devices from within ioter.
  • Automated testing: Repeated testing through scripts can validate device stability and connection.

ioter emulates all Matter supported devices with a Linux PC and Thread RCP dongle. ioter runs the All Cluster App of Matter on a Linux PC to emulate multiple instances of various Matter supported IoT nodes. Each of these IoT nodes uses the underlying Thread RCP-based USB dongle (radio) for data transmission. By using the SmartThings Station as a border router and SmartThings Application along with emulated IoT nodes, we can configure a smart home.

Overview

Required tools

Before diving into this tutorial, ensure you have the following prerequisites set up on your development environment:

  • Bluetooth-enabled, Windows desktop or laptop

  • Ubuntu 22.04 (previous versions may have Bluetooth conflicts)
    All installation instructions have been validated on Ubuntu 22.04 LTS.

  • USB hub with power input (USB3.0 recommended)

  • Thread RCP USB dongle. We verified with these:

Nordic nrf52840 OT RCP dongle guide

Nordic nrf52840-DK board OT RCP board guide

  • Phone with latest SmartThings App installed
  • An onboarded Samsung SmartThings Station or SmartThings hub.

1. Set up your nRF 52840 OpenThread RCP dongle

OpenThread RCP is used to connect to the Thread network. Apply the Thread RCP firmware to the nrf52840 dongle:

  1. Install 'nRF Connect for Desktop' on a Windows PC from Nordic Semiconductor site

  2. Execute 'nRF Connect for Desktop'

  3. Install and open 'Programmer'

  4. Before selecting a device, insert the dongle and press the button shown in the red box in the image below to enter download mode.

  5. In 'SELECT DEVICE' option , select the inserted nrf52840 dongle.

  6. In 'Add file,' select RCP firmware file ot-rcp-18b6f94.hex (RCP version 6)

  7. Select 'Write' to flash the firmware.

Your OpenThread RCP dongle creation is complete and ready for testing!

2. Install ioter

Clone the ioter repository and install ioter on your system.

  1. Clone the ioter repository in your current directory:
    git clone https://github.com/Samsung/ioter.git

  2. Install ioter on your local machine:
    cd ioter
    ./script/setup

  3. Execute ioter:
    ./script/run

Docker image support

Alternatively, you can use a Docker image with an ‘ioter' environment. We have confirmed that it is working on the host operating systems listed below:

  • Ubuntu Lunar 23.04
  • Ubuntu Jammy 22.04 (LTS)
  • Ubuntu Focal 20.04 (LTS)
  • Ubuntu Bionic 18.04 (LTS)

The following host operating systems are unsupported, but may work:

  • Ubuntu Xenial 16.04
  • macOS
  • Any OS running on an ARM platform such as Raspberry Pi

Configure the server

Configure your host with the following settings:

  1. Set xhost to connect to X server and use X11:
    $ xhost +local:root

  2. (For Ubuntu 23.04 only) Stop the wireplumber service process that keeps the Bluetooth service running:
    $ systemctl --user stop wireplumber

  3. Turn off the Bluetooth service:
    $ systemctl stop bluetooth
    or
    $ service bluetooth stop

Run Docker container

Start the Docker container with the following command:

sudo docker run --rm -it -e DISPLAY=$DISPLAY \
-v [HOST_ioter_PATH]:/home/iot/ioter \
-v /tmp/.X11-unix:/tmp/.X11-unix \
-v "$HOME/.Xauthority:/root/.Xauthority:ro" \
--device=[DEVICE_NODE_PATH] \
-v /dev:/dev \
--privileged \
--net=host \
--cap-add=NET_ADMIN --cap-add=SYS_ADMIN \
docker.io/spdkimo/ioter:[VERSION] \
python3 ioter/src/main.py

Where:

3. Onboard Matter supported IoT devices

Reminder: Before you start using ioter, ensure SmartThings Station has been onboarded in the Samsung SmartThings App.

When you initiate ioter with a run script, the main window appears with a list of devices.

  1. Select the device: Press on the Start Button, the device control window appears

  2. In the SmartThings App, click on the add device button in the upper right corner. Use Scan QR code or Scan for nearby devices to start onboarding.

  3. Use the QR code and/or paring code (created in Step 1) to proceed with the onboarding.

After onboarding the device, you can control the device states with ioter or the mobile app. The below example demonstrates controlling the on/off states of a light bulb.

4. Automated testing

Use Automations to validate the connectivity and stability of various IoT device types. Some examples of how you can do this include:

  • Test multiple devices in a loop
  • Use the + or - button to add/remove on-boarded device or sleep commands

Automation scrips are saved in XML format and can be loaded on demand. Once executed, the progress bar shows the current completion percentage.

Pro Tips:

  • Device/sleep commands can be reordered by using the ↑ and ↓ buttons.
  • Log Window shows the current activities including script loads, executions, saves, and number of successful/unsuccessful commands.

Reference:

  1. Starts/Ends the loop.
  2. Add the command of the on-boarded device .
  3. Add sleep for the given interval.
  4. Device Type (for example, Light Bulb, Contact Sensor, or Door Lock).
  5. Device types supported commands (for example, On/Off or Level Control).
  6. Device command’s value (for example, Light Bulb is On or Off).
  7. Sleep Interval, in seconds.
  8. Loop count and loop interval, in seconds.
  9. Clears all loops and commands.
  10. Runs the automation script.
  11. Clears the log window.
  12. Script completion progress bar.
  13. The log window, which shows current activities.

Next steps

ioter is a powerful tool to help you onboard and test various types of IoT devices in a virtual smart home environment.

Now that you have a solid foundation, explore ioter's features and start testing any Matter Thread compliant IoT devices. If you encounter any issues or have any questions, please do reach out on our ioter Github repository or the developer section of our SmartThings Community Forums.

Recent Posts