SiLicon Labs Direct Connect Tool#

In the fast-paced world of industrial IoT and on-site debugging, maintaining reliable and direct communication with devices is critical. Yet, traditional methods often depend on the device’s integration within its network, adding layers of complexity when immediate access is needed. Direct Connect is a groundbreaking interface designed to bridge that gap through a seamless wireless link that supports IPv6 traffic.

What sets Direct Connect apart is its independence from the Wi-SUN network. Whether the device is fully joined, in the process of joining, or completely disconnected from the network, Direct Connect ensures uninterrupted access. This capability makes it an invaluable tool for industrial implementations, where devices often operate in dynamic environments with evolving network conditions.

With Direct Connect, technicians and engineers can directly interface with Wi-SUN devices to perform diagnostics, deploy updates, or test configurations without the need to rely on the device's network status. This Silicon Labs solution not only simplifies on-site debugging but also enhances operational efficiency by eliminating the downtime associated with network dependencies.

LimitationsDirect Connect Tool is only supported on FFNs, LFNs do not support this feature.

Direct Connect ArchitectureDirect Connect Architecture

Prerequisites#

Direct connect well functioning relies on two main entities, the Direct Connect client that runs on a Linux host plus the RCP, and the Direct Connect Server that runs on the targeted Wi-SUN node. For this user guide we will need:

And on the software side, we will use:

Setup Preparation#

Linux Host#

The Direct Connect tool is delivered with the wisun-br-linux tools package and called silabs-ws-dc.

To install silabs-ws-dc on the Linux host, start by cloning the wisun-br-linux repository.

git clone https://github.com/SiliconLabs/wisun-br-linux.git

After cloning the repository, refer to Compiling section in wsbrd-br-linux to install the necessary dependencies and mbedTLS. Then, run the following cmake command instead of the one in the readme to install silabs-ws-dc.

mkdir build && cd build && cmake -G Ninja -DCOMPILE_DEVTOOLS=true ..
ninja
sudo ninja install

Wi-SUN RCP#

The silabs-ws-dc tool uses the same RCP that works with wsbrd that is delivered in SiSDK 2024.12.0. To get the RCP project, install Simplicity Studio v5 and follow this guide to install the SiSDK Package.

After installing Studio and the required SDK follow those steps to flash the Wi-SUN RCP to the board.

Flashing the Wi-SUN RCP#

  1. In the Debug Adapters view, select the device to be used as the Wi-SUN RCP.

  2. Navigate to the EXAMPLE PROJECTS & DEMOS tab and turn off the Example Projects filter.

  3. Click RUN next to the Wi-SUN – RCP project.

    Screenshot showing the Wi-SUN - RCP ProjectScreenshot showing the Wi-SUN - RCP Project

Wi-SUN Node#

The Wi-SUN - CLI example provide a set of command lines to evaluate the Direct Connect tool. The following steps explains how to flash the Wi-SUN - CLI example to the board.

Flashing the Wi-SUN - CLI example#

  1. In the Debug Adapters view, select the device to be used as the Wi-SUN CLI.

  2. Navigate to the EXAMPLE PROJECTS & DEMOS tab and turn off the Example Projects filter.

  3. Click RUN next to the Wi-SUN - CLI example project.

Direct Connect Configuration#

Configuring the Direct Connect tool involves setting up two key components: the Direct Connect server and the Direct Connect client. For a successful and secure connection, it’s critical that both the server and client configurations are synchronized, particularly regarding the Pairwise Master Key (PMK) and the Wi-SUN node MAC address.

The PMK is the encryption key that ensures secure communication between the server and the client. Both sides must use the same PMK to establish a trusted and encrypted link. A mismatch in the PMK will result in connection failure, as the Direct Connect tool relies on this shared key for authentication and data protection.

Having the same PMK on both sides allows to establish a direct connection without performing the Wi-SUN authentication flow (EAP-TLS), removing the need of an authentication server and additional certificates.

Direct Connect Client#

The Direct Connect client’s configuration is managed through the silabs-ws-dc configuration file, allowing precise customization to establish a secure link with a Wi-SUN device. This connection is built around two critical parameters: the MAC address (EUI-64) of the target device and the Pairwise Master Key (PMK). These elements ensure that communication is uniquely tied to the intended device, providing robust security and preventing unauthorized access.

An example configuration file is provided in the wisun-br-linux/examples directory. You can use this example as a starting point by either modifying it directly or creating a new configuration file based on your specific setup requirements.

Below is an example configuration that highlights key settings:

# Path of the serial port connected to the RCP.
uart_device=/dev/ttyACM0

# Serial baudrate in bps
uart_baudrate=115200

# PHY Configuration
domain=EU
chan_plan_id=32
phy_mode_id=1

# Target MAC address
target_eui64=b4:35:22:ff:fe:98:29:ff

# Pairwise Master Key
target_pmk=34:ba:32:26:a0:b2:ad:66:7c:9f:66:02:e5:db:75:77:dd:bd:5d:2b:34:3a:93:06:2b:90:c0:7b:e2:8e:4e:54

Direct Connect Server#

The server-side configuration must mirror the client in terms of the PMK value. While the MAC address identifies the target device on the client side, the server only needs the shared PMK and the same PHY configuration of silabs-ws-dc to establish a secure session.

To configure the Wi-SUN Node, connect to the console in Simplicity Studio. In the Debug Adapters view, right click on the Wi-SUN node board and select launch Console. To get a prompt on the Console, go to the Serial 1 tab and press Enter.

Setting the Pairwise Master Key#

Run the following command in the Wi-SUN node console to set the PMK:

wisun set wisun.direct_connect_pmk 34:ba:32:26:a0:b2:ad:66:7c:9f:66:02:e5:db:75:77:dd:bd:5d:2b:34:3a:93:06:2b:90:c0:7b:e2:8e:4e:54

Enable Direct Connect#

Once the PMK is set, you need to explicitly enable the Direct Connect feature on the server. This step activates the feature, allowing the Direct Connect server to connect with the Direct Connect client.

Run the following command to enable Direct Connect:

wisun set_direct_connect_state 1 (1 to enable, 0 to disable)

Direct Connect in Action#

Establishing the Direct Connect Link#

To establish a Direct Connect link, the process begins with the Direct Connect client initiating communication with the target device.

Run silabs-ws-dc to Initiate the Connection#

On the Linux host execute the following command:

sudo silabs-ws-dc -F ./silabs-ws-dc.conf

This command starts the Direct Connect client using the configuration file silabs-ws-dc.conf and sends a Direct Connect Solicit frame to the target device. This frame serves as a request for the device to establish a connection with the client.

Receiving the Direct Connect Request#

On the targeted Wi-SUN device, the Wi-SUN - CLI example will indicate receipt of the request with a message like:

[Direct Connection request from fe80::b635:22ff:fe98:29b2]

The fe80::b635:22ff:fe98:29b2 is the link-local IPv6 address used by silabs-ws-dc. This address will vary depending on your specific setup.

Accepting the Direct Connect Link#

To accept the incoming connection request, run the following command on the Wi-SUN - CLI example:

wisun accept_direct_connect_link fe80::b635:22ff:fe98:29b2

If successful, the Wi-SUN - CLI example will display:

[Accepted connection request]

Confirmation of a Successful Connection#

Once the connection is fully established, both the Wi-SUN - CLI example and the silabs-ws-dc tool will provide confirmation messages:

  • On the Wi-SUN CLI example:

    [Direct Connect Link fe80::b635:22ff:fe98:29b2: connected]

  • On the silabs-ws-dc logs:

    Direct Connection established with b4:35:22:ff:fe:98:29:ff
b4:35:22:ff:fe:98:29:ff reachable at fe80::b635:22ff:fe98:29ff

Using and Managing the Direct Connect Link#

Once the Direct Connect link is established, it provides a secure, point-to-point communication channel that supports UDP, TCP, and ICMP traffic. This enables a wide range of networking operations such as testing, debugging, and data exchange between the Direct Connect Client and the Direct Connect Server.

Using the Link#

  • Versatility: The link operates independently of the Wi-SUN network status, meaning it functions whether the device is connected to a Wi-SUN network or not.

  • Direct Communication: Communication is exclusively between the Direct Connect Client and Server. Routing to other devices within the Wi-SUN network is not supported. This ensures that the connection remains private and direct, focusing solely on the configured devices.

This direct access is particularly useful for performing device-specific diagnostics, deploying configurations, or running network tests without relying on the broader Wi-SUN infrastructure.

Closing the Link#

To terminate the Direct Connect link, simply stop the silabs-ws-dc process on the client using Ctrl+C or the following command if the client is running in the background:

sudo pkill silabs-ws-dc

Once the client stops, the link will disconnect automatically. After 60 seconds, the Wi-SUN - CLI example will display the following message, confirming the disconnection:

[Direct Connect Link fe80::b635:22ff:fe98:29b2: disconnected]

Connection Troubleshooting#

Connection loss#

If the Direct Connect client loses connection with the server, it will automatically try to reconnect by sending Direct Connect Solicit frames again and indicate the following:

Direct Connection with b4:35:22:ff:fe:98:29:ff lost, attempting to reconnect...

Connection failure#

If the silabs-ws-dc is unable to establish a Direct Connection with the server, it will indicate the following:

b4:35:22:ff:fe:98:29:ff is unreachable, please check your configuration

In that case, make sure that the used parameters are set accordingly on both sides, refer to Direct Connect Configuration.

The Wi-SUN CLI may also indicate the following after accepting the direct connection:

[Direct Connect Link fe80::b635:22ff:fe98:29b2: error]

In that case, make sure the PMK used is the same on both sides and restart silabs-ws-dc.

Final Thoughts#

The Direct Connect link offers a powerful and secure way to interact with Wi-SUN devices, making it an essential tool for industrial IoT applications. Its independence from the Wi-SUN network ensures flexibility, while its direct communication channel guarantees simplicity and reliability. Managing the link, from initiation to closure, is straightforward, making it a valuable asset for engineers and developers.