Skip to Content

U-PHY™ Quick Start Guide on Linux®

Last modified by Microchip on 2026/11/05 14:47

Introduction

Thank you for taking the time to evaluate our U-PHY™ solution on Linux®.

This guide provides instructions on how to:

  • Run a pre-built U-PHY demo application
  • Use a diagnostic tool to view the device
  • Run the demo application as a PROFINET®, EtherNet/IP™, MODBUS® TCP or CC-Link IE™ device and establish an IO connection
  • Build the demo application
Information

Prerequisites:

  • Hardware
    • One of the following Microchip development boards:
    • Serial-to-USB adapter
    • Ethernet cable (a standard Ethernet connection is preferred over a USB-to-Ethernet adapter)
  • Software and tools
Warning

Please refer to the "Troubleshooting" section of this page for assistance.

Setup Instructions

Set up the Board

Please refer to the board-specific section below as needed to connect the peripherals described in the following steps.

Failed to execute the [display] macro. Cause: [Current user [null] doesn't have view rights on document [xwiki:Development.applications.industrial-communications.display-macros.sam9x75-curiosity-lan-kit-setup-instructions.WebHome]]. Click on this message for details.

Failed to execute the [display] macro. Cause: [Current user [null] doesn't have view rights on document [xwiki:Development.applications.industrial-communications.display-macros.sam9x60-curiosity-kit-setup-instructions.WebHome]]. Click on this message for details.

Failed to execute the [display] macro. Cause: [Current user [null] doesn't have view rights on document [xwiki:Development.applications.industrial-communications.display-macros.sama7d65-curiosity-kit-setup-instructions.WebHome]]. Click on this message for details.

Failed to execute the [display] macro. Cause: [Current user [null] doesn't have view rights on document [xwiki:Development.applications.industrial-communications.display-macros.sama7g54-evaluation-kit-setup-instructions.WebHome]]. Click on this message for details.

Setup the Serial Terminal

On your PC, open a serial terminal and configure it with the following settings:

  • Baud Rate: 115200
  • Data: 8-bit
  • Parity: None
  • Stop Bits: 1
  • Flow Control: None

Failed to execute the [display] macro. Cause: [Current user [null] doesn't have view rights on document [xwiki:Development.applications.industrial-communications.display-macros.serial-terminal-windows-pc.WebHome]]. Click on this message for details.

Failed to execute the [display] macro. Cause: [Current user [null] doesn't have view rights on document [xwiki:Development.applications.industrial-communications.display-macros.serial-terminal-setup.WebHome]]. Click on this message for details.

Configure a static IP address for the Windows PC Ethernet interface connected to the U-PHY device.

Go to Windows Settings > Network & internet.

Select the appropriate Ethernet interface, change the IP configuration to Manual, and configure the IP address and Subnet mask accordingly.

Edit IP Settings window

Success

Congratulations! Setup is completed.

Back to Top

Running the Pre-Built Demo Application

Information

Note: This section provides instructions on how to program and execute the pre-built U-PHY demo application.

Download the ZIP release package file from SW85W77A and extract its content.

Flash the extracted image onto the SD card.

Open balenaEtcher.

balena

Click on Flash from file and select a pre-built image from the uphy-stack-linux/bin/<devicename> folder.

  • Files with the *.wic extension are Yocto Project® images.
  • Files with the *.img extension are Buildroot™ images.

Click on Select target and choose the mounted SD card. Then, click Flash to begin the installation process.

After the flashing process is complete, insert the SD card into the on-board SD card slot.

Press the RESET button on the board to initiate a reset.

The Linux image will boot, and a login prompt will appear in the serial terminal.

If you are not automatically logged in, enter "root" as the username.

You may be asked then to change your password:

login

Enter below command in the terminal to start the U-PHY application with the desired protocol.

  • /usr/bin/uphy <protocol> <network interface>

Where <protocol> can be either profinet, ethernetip, modbus or cclink.

Run "ip link show up" command to get the name of the <network interface>.

ip link show

start u-phy

Information

Note: The remainder of this guide assumes the network interface is eth0. It can have a different value depending on the board and build.

Success

Congratulations! The U-PHY demo application is now running successfully.

Back to Top

Observing U-PHY PROFINET® With PRONETA® BASIC

Information

Note: This section explains how to view and configure the U-PHY PROFINET device demo application using PRONETA® diagnostic tool.

PRONETA is a Siemens® diagnostic tool designed for analyzing and configuring PROFINET networks.

Warning

Since PRONETA is compatible exclusively with Windows OS, this section can only be completed on a Windows-based PC.

Reset the board and enter "/usr/bin/uphy profinet eth0" in the terminal.

Download PRONETA BASIC 3.8 (or higher) from Siemens by logging in with a free account.

Locate the ZIP file in the downloads section, download it, and extract its contents.

Run PRONETA.exe. If prompted to install the Npcap driver and click Yes to proceed.

Once the PRONETA window opens, navigate to the Settings menu.

PRONETA window

In the Network Adapter menu, select the network adapter that is connected to the PROFINET device.

PRONETA - Siemens window

 

Navigate to the Network Analysis menu and select the Online tab.

The PC running PRONETA and the device running the PROFINET demo application will be displayed.

PC running PRONETA and the device running the PROFINET demo application

 Right-click on the device and select Start Flashing LED.

The LED on the development kit will blink three times at a frequency of 1 Hz and will continue blinking with a short pause between cycles until you right-click on the device and select Stop Flashing LED.

Start Flashing LED option

Warning

The Set/Reset Network Parameters options are functional: they allow setting/resetting the IP address.

The Open Web Browser option is not supported by the demo application.

Success

Congratulations! You are now able to view and configure the U-PHY PROFINET device demo application using PRONETA diagnostic tool.

Back to Top

Setting a Static IP Address for the U-PHY Device

Information

Note: EthernetNET/IP, MODBUS TCP and CC-Link IE protocols require the device to have an IP address by default.
The IP address can be statically assigned or assigned by a DHCP server. 

This section explains how to set a static IP address for the U-PHY Device.

Set a static IP address for the device. You can use your preferred IP address and netmask is set to 255.255.255.0.

ifconfig eth0 192.168.0.50

The required IP address will be set.

set ip

Back to Top

Observing U-PHY EtherNet/IP™ With Hilsher EtherNet/IP Tool

Information

Note: This section explains how to view the U-PHY EtherNet/IP device demo application using Hilscher EtherNet/IP tool.

Warning

Since Hilscher EtherNet/IP tool is compatible exclusively with Windows OS, this section can only be completed on a Windows-based PC.

Reset the board and enter "/usr/bin/uphy ethernetip eth0" in the terminal.

Download latest Hilscher EtherNet/IP Tool and extract its contents.

Run EtherNetIPTool.exe. Click Preferences and choose the  IP address of your interface in the Local NIC drop down menu.

preference

Click on the Send ListIdentity Request (UDP broadcast). Our device should be visible in List of identified devices. Click on it to view the device details.

eip_tool

Success

Congratulations! You are now able to view the U-PHY EtherNet/IP device demo application using Hilscher EtherNet/IP Tool.

Back to Top

Establishing I/O Connection (PROFINET, Ethernet/IP and MODBUS TCP)

Information

Note: This section outlines the procedure for establishing an IO connection between a CODESYS SoftPLC and the U-PHY device demonstration application using different industrial protocols.

Warning

This section is performed on a Windows-based PC as a continuation of the previous section.

Download CODESYS Development System V3 and install it on the Windows machine.

Information

Note: This guide is based on CODESYS V3.5 SP22 Patch 2. Please note that menu names and layouts may vary if you are using a different version. We recommend using the latest version of all software components whenever possible.

Warning

If your Windows machine firewall is enabled, make sure to add CODESYS Control Win application (i.e., CODESYSControlService.exe) to the firewall allowed list so it can receive Ethernet packets.

In the Windows taskbar system tray, right-click the CODESYS Control Win Systray icon and select Start PLC.

CODESYS Control Win SysTray bar

Click OK if the window in the accompanying image appears.

CODESYS Control Win SysTray window

Launch CODESYS from the Start menu.

Navigate to Tools > CODESYS Installer, and install the CODESYS Control Win add-on.

CODESYS Installer window

Navigate to Tools > Device Repository.

PROFINET Case:

Click Install and select the GSD file ((GSDML-V2.44-RT-Labs-U-Phy-DIGIO-Sample-20260223.xml) located in uphy-stack-linux/share to install the PROFINET device.

Device Repository dialog

GSD

EtherNet/IP Case:

Select U-Phy DIGIO Sample.eds located in uphy-stack-linux//src/share to install the Ethernet/IP adapter.

EDS

Information

Note: MODBUS TCP server does not have a description file to be installed.

Navigate to File > Open Project and select uphy-stack-linux/codesys/uphy_demo_controller_win.project to load the project.

If the window in the accompanying image appears, click on Set All to Newest and then click OK.

Set All to Newest

The project is now loaded.

uphy_demo_controller_win.project window

Double-click on Device (CODESYS Control Win…).

In the Communication Settings section, click Scan Network and select your PC from the list.

Communication settings

This will display the following result:

Scan results

 

Double-click on Ethernet.

In the General tab, click Browse.

Ethernet tab

Warning

When performing this step for the first time, you may be prompted to create a username and password.

CODESYS dialog

Click Yes and ensure you record the username and password for future reference.

If you are asked to log in, enter the username and password you just created:

Device User Logon dialog

Select the network adapter connected to the U-PHY device.

The IP address will be updated accordingly.

 Network and Internet settings

Double-click on PN_Controller.

In the General tab, click Adjust to set proper values for Default Slave IP Parameter.

PN_Controller tab

This configuration should result in the following:

Default slave IP parameter

Go to Ethernet > PN_Controller > U_Phy_DIGIO_Sample.

In the General tab, set an IP address for the PROFINET device. In this guide, we use 192.168.0.50.

pnet ip

Go to Ethernet > EtherNet_IP_Scanner > U_Phy_DIGIO_Sample_1.

In the General tab, set the IP address to the same value which was set on the device using the command uphy_set_ip.

eip ip

Go to Ethernet > Modbus_TCP_Client > Modbus_TCP_Server.

In the General tab, set the IP address to the same value which was set on the device using the command uphy_set_ip.

mbus ip

Go to the Online menu and select Login.

If prompted by a confirmation window, click Yes.

CODESYS dialog

Go to the Debug menu and select Start.

Debug menu

The Programmable Logic Controler (PLC) on the Windows PC will be in RUN mode, as indicated in the status bar at the bottom of the CODESYS window.

RUN mode

Follow these steps for PROFINET use case.

Reset the board and enter "/usr/bin/uphy profinet eth0" in the terminal.

Go to Ethernet > PN_Controller > U_Phy_DIGIO_Sample.

In the General tab, the Status will be OK if a PROFINET connection is established to the U-PHY device.

P_Net_multi_module_sample_app tab

Go to Step 16.

Warning

If the connection fails, verify the following points:

  • Ensure that Npcap is installed on the PC.
  • If your Windows machine firewall is enabled, make sure to add CODESYS Control Win application (i.e., CODESYSControlService.exe) to the firewall allowed list so it can receive Ethernet packets.

Follow these steps for EtherNet/IP use case.

Reset the board and enter "/usr/bin/uphy ethernetip eth0" in the terminal.

Go to Ethernet > EtherNet_IP_Scanner > U_Phy_DIGIO_Sample_1.

In the Status tab, the status will be Running if a connection is established to the U-PHY device.

eip

Go to Step 16.

Warning

If the connection fails, verify the following points:

  • Ensure that Npcap is installed on the PC.
  • If your Windows machine firewall is enabled, make sure to add CODESYS Control Win application (i.e., CODESYSControlService.exe) to the firewall allowed list so it can receive Ethernet packets.

Follow these steps for MODBUS TCP use case.

Reset the board and enter "/usr/bin/uphy modbus eth0" in the terminal.

Go to Ethernet > Modbus_TCP_Client > Modbus_TCP_Server.

In the Status tab, click on Acknowledge. Then the ModbusTCPServer status will be Running if a connection is established to the U-PHY device.

eip

Go to Step 16.

Warning

If the connection fails, verify the following points:

  • Ensure that Npcap is installed on the PC.
  • If your Windows machine firewall is enabled, make sure to add CODESYS Control Win application (i.e., CODESYSControlService.exe) to the firewall allowed list so it can receive Ethernet packets.

This step is common for all use cases.

Double-click on PLC_PRG to look at the project code.

Information

Note: The out_led_xxxx variable is a PLC output that controls the LED on the U-PHY device, while in_pin_button_LED is a PLC input that provides the status of the USER button on the U-PHY device.

The flashing bit will toggle when the on-board USER push button is pressed.

If the flashing bit is set to TRUE, out_led_xxxx will toggle continuously, causing the LED on the U-PHY device to blink.

PLC_PRG tab

The User LED should now be toggling.

If the U-PHY device is reset, the User LED will be either toggling or OFF based on the state of the flashing bit.

Success

Congratulations! You have successfully established an I/O connection to the U-PHY device.

Back to Top

Establishing I/O Connection (CC-Link IE™)

Information

Note: This section outlines the procedure for establishing an IO connection between a CC-Link IE master running on Windows and the U-PHY device demonstration application running CC-Link IE slave.

Reset the board and enter "/usr/bin/uphy cclink eth0" in the terminal.

Open a terminal on your Windows PC and go to uphy-stack-linux/bin. Execute below command: 

cl_sample_master.exe -m <PC-IP-Address> -s <UPHY-IP-Address> -n 3

CC-Link

Press the on-board USER push button to enable/disable toggling of User LED.

 

Success

Congratulations! You have successfully established a CC-Link IE I/O connection to the U-PHY device.

Back to Top

Building the Demo Application

Information

Note: This section provides instructions on how to build the U-PHY device demo application from source and run it.

The demo application includes:

  1. A u-phy meta layer, which can be integrated into a Yocto Project build
  2. A u-phy Buildroot package that can be incorporated into a Buildroot build

Yocto Project Build

Install the following packages on your Linux PC:

sudo apt-get install gawk wget git-core git-lfs diffstat unzip texinfo gcc-multilib \
     build-essential chrpath socat cpio python3 python3-pip python3-pexpect \
     xz-utils debianutils iputils-ping python3-git python3-jinja2 liblz4-tool xterm repo

Clone the required repositories.

  • Create an empty directory to serve as your workspace:
mkdir yocto-dev
cd yocto-dev
  • Set the language settings environment variable:
export LC_ALL=C
  • Set git email and user:
git config --global user.email "Your email"
git config --global user.name "Your Name"
  • Use the repo tool to download all the required repositories:
repo init -u https://github.com/linux4microchip/meta-mchp-manifest.git -b refs/tags/linux4microchip-2026.04 -m mpu/default.xml

repo sync

Copy the uphy-stack-linux/meta-uphy directory to the yocto-dev directory.

Modify the EXTERNALSRC path in yocto-dev/meta-uphy/recipes-uphy/uphy-demo/uphy-demo_1.0.bbappend to reference the absolute path of uphy-stack-linux/src.

Initialize the build environment.

The meta-mchp repository includes sample configuration templates to help set up BitBake layers and key configuration files in the Yocto Project build directory.

  • Set the TEMPLATECONF environment variable to the appropriate configuration template before initializing the build environment:
export TEMPLATECONF=${TEMPLATECONF:-../meta-mchp/meta-mchp-mpu/meta-mchp-mpu-apps/conf/templates/default}
  • Navigate to the yocto-dev directory and initialize the Yocto Project build environment:
source openembedded-core/oe-init-build-env
  • To enable the meta-uphy layer during the build, edit yocto-dev/build/conf/bblayers.conf and add the meta-uphy layer:
BBLAYERS ?= " \
/<path-to-yocto-dev>/yocto-dev/openembedded-core/meta \
...
/<path-to-yocto-dev>/yocto-dev/openembedded-core/../meta-uphy \
"
  • To include the U-PHY demo application and SNMP server in the image, add the following line at the bottom of yocto-dev/build/conf/local.conf:
CORE_IMAGE_EXTRA_INSTALL += "uphy-demo net-snmp-server-snmpd"

Build the image.

  • Depending on your target machine, execute one of the following commands:
export MACHINE=sam9x75-curiosity-sd
export MACHINE=sam9x60-curiosity-sd
export MACHINE=sama7d65-curiosity-sd
export MACHINE=sama7g5ek-sd
  • Navigate to the yocto-dev directory and build the project:
bitbake mchp-headless-image
  • After the build completes successfully, please follow the steps outlined above to run the newly built demo application.
Information

Note: The SD card image with the .wic extension is located in the yocto-dev/build/tmp-glibc/deploy/images/"MACHINE" folder.

 

Success

Congratulations!

You have successfully rebuilt the U-PHY device demo application using Yocto Project build system.

Buildroot Build

Install the following packages on your Linux PC:

sudo apt-get install subversion build-essential bison flex gettext \
libncurses5-dev texinfo autoconf automake libtool mercurial git-core \
gperf gawk expat curl cvs libexpat-dev bzr unzip bc python3-dev \
wget cpio rsync xxd bmap-tools

Clone the required repositories.

  • Create an empty directory to serve as your workspace:
mkdir buildroot-dev
cd buildroot-dev
  • Clone the required repositories:
git clone https://github.com/linux4microchip/buildroot-mchp.git
git clone https://github.com/linux4microchip/buildroot-external-microchip.git
  • Check out the following release branch:
cd buildroot-external-microchip/
git checkout linux4microchip-2026.04 -b linux4microchip-2026.04
cd ../buildroot-mchp/
git checkout linux4microchip-2026.04 -b linux4microchip-2026.04

Copy uphy-stack-linux/uphy-br folder to buildroot-dev/buildroot-external-microchip/package folder.

Add the following line to buildroot-external-microchip/Config.in:

source "$BR2_EXTERNAL_MCHP_PATH/package/uphy-br/Config.in"

Initialize the build environment:

  • Navigate to the buildroot-mchp directory and set up BR2_EXTERNAL:
export BR2_EXTERNAL=../buildroot-external-microchip/
  • Run the defconfig for your board by executing one of the following commands:
make sam9x75_curiosity_headless_defconfig
make sam9x60_curiosity_headless_defconfig
make sama7d65_curiosity_headless_defconfig
make sama7g5ek_headless_defconfig
  • Open the Buildroot configuration menu:
make menuconfig
  • Enable the following packages:
    • u-phy:
      • Go to External Options > uphy and press y. This will display the uphy repo path or URL option.
      • Enter the full path to the uphy-stack-linux/ folder:
      •  
    • packages
    • snmp:
      • Exit External Options > uphy to come back to the main menu.
      • Go to Target packages > Networking applications > netsnmp and press y.
  • Save and Exit the configuration menu.

Build the Image

$ make

After the build completes successfully, please follow the steps outlined above to run the newly built demo application.

Information

Note: The SD card image is located in buildroot-mchp/output/images/sdcard.img folder.

Success

Congratulations!

You have successfully rebuilt the U-PHY device demo application using Buildroot lightweight build system.

Back to Top

Next Steps

For detailed instructions, please refer to the U-PHY User Manual located in the uphy-stack-linux/ folder.

Back to Top

Troubleshooting

There is no communication when running my CODESYS project.

If the connection fails with CODESYS, verify the following points:

  • Ensure that Npcap is installed on the PC.
  • If your Windows machine firewall is enabled, make sure to add CODESYS Control Win application (i.e., CODESYSControlService.exe) to the firewall allowed list so it can receive Ethernet packets.
  • Prefer a standard Ethernet connection over a USB-to-Ethernet adapter.

The serial terminal is not displaying any output.

If the terminal does not display any output, consider the following possible causes:

  • Ensure that the RX and TX signals of the serial cable are correctly connected to the corresponding RX and TX signals on the board.
  • Confirm that the ground signal is properly connected.
  • Verify that the SD card contains the correct files.

The terminal only displays RomBOOT message.

  • Ensure that the SD card contains the correct files and is inserted properly.

The image on the SD card is not booting.

  • Confirm that the jumpers for Quad Serial Peripheral Interface (QSPI) Flash and NAND Flash are open to prevent the system from booting a different image.

Back to Top