Drive-On-Chip with PLC Design Example for Agilex™ 5 Devices¶

Overview¶

This example demonstrates:

Use of a Programmable Logic Controller (PLC) runtime to control FPGA IP via an IEC 61131 PLC application.
Embedded Real Time Dual Axis motor control in the FPGA fabric.
Deployment of a Docker container on the Agilex™ SoC HPS running Linux.
Monitoring the motor drives via the Python GUI and JTAG interface.

Programmable Logic Controller¶

The Programmable Logic Controller has been a fundamental component of industrial automation for decades. The IEC 61131-3 standard that defines the programming languages of these devices provides compatibility across different manufacturers and a familiar programming environment for the technicians who install and configure them.

The Drive-on-Chip with PLC Design Example for Agilex™ 5 Devices shows how the PLC programming environment can be used to interface to Motor Control Soft IP in the FPGA fabric. The design example combines a PLC Runtime, webserver and multi-axis simulated motor drives. The PLC runtime runs PLC applications. The webserver provides the interface to monitor the motor drives. The design includes a motor and power board model on the FPGA that removes the need for a physical motor setup.

The following diagrams provide an overview of the interaction of software running on ARM CPUs inside the Hard Processor Subsystem (HPS) and hardware components running in the programmable logic (FPGA) parts of the device.

For more information of ARM HPS in Altera® Agilex Devices refer to User Manuals section.

High-Level Block Diagram of the Drive-OnChip
with PLC Design Example.

The previous figure shows that the PLC Runtime and webserver run in a Docker container on the HPS Operating System (OS, Custom Linux). The Docker container separates the applications from the operating system. The container includes the runtime libraries and software utilities required by the PLC application to run. The connections to the operating system are the only interfaces needed for the motor control and web interface to execute.

The Drive-On-Chip (DoC) Python GUI monitors the simulated motor axes. The connection to the Drive-on-Chip IP in the FPGA is a JTAG interface that bypasses the HPS. The GUI provides a confirmation of the activity of the motor axes independent of the software on the HPS.

Pre-requisites¶

Software Requirements to run¶

The following are required to be able to fully exercise the Agilex™ 5 Modular Development Kit:

Host PC with
- 8 GB of RAM. Less will be fine for only exercising the binaries, and not rebuilding.
- Linux/Windows OS installed.
- Serial terminal (for example GtkTerm or Minicom on Linux and TeraTerm or PuTTY on Windows).
- Tool to write images for USB sticks or SD cards such as "DiskImager" or "Rufus".
- Altera® Quartus® Prime Pro Edition Version 24.3 Programmer and Tools.
- To run the GUI:
  - Python 3.10.5
  - Pip 22.2.2
  - Python libraries: Pyside6 (6.3.2), pyqtgraph (0.13.1), numpy (1.23.2), Python Standard Libraries: traceback, sys, re, math, struct, subprocess, os, time, threading.

Software Requirements to build¶

Linux OS installed.
62 GB free storage (~2GB for Quartus® Build and ~60GB for YOCTO/KAS build).
350 MB for Docker Container Cross-Compilation.
Python/PIP/KAS for Yocto Build (or a suitable container).
Docker Engine Version 26.0 or later with Buildx support for ARM64.
Full Altera® Quartus® Prime Pro Edition Version 24.3
FPGA NiosV/g Open-Source Tools 24.3 (installed with Quartus® Prime).
Altera® Quartus® Agilex™ 5 Support.
MATLAB 2021b with Simulink (Optional).
DSP Builder for Altera® FPGAs Pro Edition v24.3 (Optional).

Hardware Requirements¶

Altera® Agilex™; 5 FPGA E-Series 065B Modular Development Kit, ordering code MK-A5E065BB32AES1. Refer to Agilex™ 5 FPGA E-Series 065B Modular Development Kit for more information about the development kit.
Power supply.
2 x Micro USB Cable.
- USB cable (USB A to micro USB) – JTAG connector.
- USB cable (USB A to micro USB) – Serial console.
Network cables.
Router (including power supply).
Micro SD card and USB card writer.

Agilex™ 5 FPGA E-Series 065B Modular Development Kit.

Sources¶

The sources listed in this table are the most current and highly recommended for Quartus® 24.3 builds. Users are advised to utilize the updated versions of these building blocks in production environments. Please note that this is a sample design and is not suitable for production or final deployment.

Example Design Source Repositories.

Component	Location	Branch
Assets Release Tag	https://github.com/altera-fpga/agilex-ed-drive-on-chip/releases/tag/rel-plc-24.3	rel-plc-24.3
Drive-On-Chip Variants	https://github.com/altera-fpga/agilex-ed-drive-on-chip	rel/24.3
Modular Design Toolkit	https://github.com/altera-fpga/modular-design-toolkit	rel/24.3
Altera FPGA PLCopen and RTMotion	https://github.com/altera-fpga/altera-openplc	main
Linux	https://github.com/altera-opensource/linux-socfpga	socfpga-6.6.22-lts
Arm Trusted Firmware	https://github.com/ARM-software/arm-trusted-firmware	socfpga_v2.11.0
U-Boot	https://github.com/altera-opensource/u-boot-socfpga	v2024.01
Yocto Project: poky	https://git.yoctoproject.org/poky	scarthgap
Yocto Project: meta-intel-fpga	https://git.yoctoproject.org/meta-intel-fpga	scarthgap

Getting Started - run with pre-build binaries¶

Follow the instructions provided in this section to run this example design in Agilex™ 5 FPGA E-Series 065B Modular Development Kit.

Download the minimum Pre-built Binaries¶

Download the Agilex™ 5 Modular Development Kit binaries that are located at:

Binaries

Boot Source	Link
SD Card Image	core-image-minimal-agilex5_modular.rootfs.wic
QSPI	top.hps.jic
Structured Language (ST) program	agilex_doc.st
GUI	doc-gui.zip

Setting Up your Development Board¶

Configure the board switches: The following provides the default configuration for all the switches in the board.

Development Board switch position.

Main configurations used in this example design

JTAG: SOM SW4[2:1]=OFF:OFF
ASx4 (QSPI): SOM SW4[2:1]=ON:ON

Connect micro USB cable from bottom left of the carrier board to PC (J35). This will be used for JTAG communication. Look at what ports are enumerated on your host computer, there should be a series of four. (See the figure below).
Connect micro USB cable from bottom right of the SOM board to PC (J2, HSP_UART). This will be used for HPS UART communication. Look at what ports are enumerated on your host computer, there should be a series of four. Use the 3^rd one in the list as the HPS serial port.(See the figure below).
If ethernet capabilities or remote connection via ssh is required connect a RJ45 cable to the ethernet port in the SOM board (J6, ETH 1G HPS)and make sure your device is in the same networks as your intended host device. After Linux boot, check the IP address of the end2 ethernet interface using ifconfig or ip a Linux commands.

USB connections to the board.

Burn the SD card image.¶

Download SD card image from the "prebuilt binaries" (<name>.wic).
Write the <name>.wic. SD card image to the micro SD card using the included USB writer in the host computer:
- On Linux, use the dd utility as shown next:
```
# Determine the device associated with the SD card on the host computer.
cat /proc/partitions
# This will return for example /dev/sd<x>
# Use dd to write the image in the corresponding device
sudo dd if=<name>.wic of=/dev/sd<x> bs=1M
# Flush the changes to the SD card
sync
```
- On Windows, use the Win32DiskImager program (or similar), available at Disk Imager. For this, first rename the .wic to an .img file (sdcard.img for example) and write the image as shown in the next figure:
Write an SD card using "Disk Imager" tool.

Turn off the board and insert the SD card in the micro SD card slot in the SOM board.

Expand the SD card Root File System Partition.¶

The Root File System partition (root, Ext4) may require resizing to accommodate larger files, such as example design applications. Users can select their preferred tool to perform this task; however, the following steps provide instructions using the Disks utility (based on e2fsprogs):

Insert the SD card image in the Linux machine that has the Disks utility installed. You should be able to see the available storage devices.
Select the root partition of the SD card and click the "gear" icon as shown in the figure below to display the menu. Navigate to Resize...

Select the "root" partition for resizing.

Use the slider to increment the partition storage capacity (the maximum is recommended). Then, click the Resize button.

Resize the root partition to the maximum.

Eject the disk safely.

Program the QSPI Flash Memory.¶

To Write/Program QSPI Flash

a. Power down board. Set MSEL dipswitch S4 on SOM to JTAG: OFF-OFF

b. Power up the board.

c. Download the JIC image, then write it to QSPI with the command. (Optional: Use the Quartus® Programmer GUI)
```
quartus_pgm -c 1 -m jtag -o "pvi;top.hps.jic" 
```
d. (Optional) Use the Quartus® Programmer GUI:
- Launch the Quartus® Programmer and Configure the "Hardware Setup..." settings as following:
Programmer GUI Hardware Settings.
- Click "Auto Detect", select the device A5EC065BB32AR0 and press "Change File.."
Programmer after "Auto Detect".
- Select your top.hps.jic (or equivalent). The MT25QU02G device should show. Select the "Program/Configure" box, and press "Start" button. Wait until completed (It could take several minutes.)
Programming the QSPI Flash with JIC file.

Power down the board. Set MSEL dip switch S4 on SOM to ASX4 (QSPI): ON-ON

Run the OpenPLC Docker Container.¶

Board and PC setup¶

Use the following diagram to connect the required equipment to run this example design.

Development Kit and PC connection diagram

Power up the board and setup the serial terminal emulator (minicom, putty, etc):
- Select the correct COMx port. From the HPS serial UART, select the third COM port (out of four).
- Serial Port configuration:
  - Baud rate: 115200, Data bits: 8, Stop bits: 1, CRC: disabled, Hardware flow control: disabled
- Connect your terminal emulator.

To continue, select method a) or method b) to deploy a Docker container image

a) Boot Linux, create a Docker image using the Dockerfile¶

In the Development Kit, wait for Linux to boot, and clone the "altera-openplc" repository:

    git clone https://github.com/altera-fpga/altera-openplc.git
    cd altera-openplc

Build the Docker Image (this can take several minutes):

    docker build -t altera-plc:arm64 .

b) Boot Linux, copy and load a cross-compiled Docker container image¶

Follow the instructions provided in Altera OpenPLC Docker Container Image Cross-compilation. to get a cross-compiled Docker image file (name it altera-plc.tar.gz)

Wait for Linux to boot and query the Development Kit IP address:

    ifconfig

The serial terminal should show the following:

Agilex™ 5 Modular Development Kit IP Address.

Take a note of the board's IP address or <dk-ip-address>

Copy the PLC docker previously generated Docker container image to the board, preferably to the /home/root directory in the RootFile System. The suggested method to do it is using scp or sftp commands to transfer the file from your host machine to the development kit.

    scp -rp altera-plc.tar.gz root@<dk-ip-address>:/home/root

Load the Image and deploy the PLC Container. To load the Docker Image use the following commands (in the Development Kit):

    docker ps -a
    docker load < altera-plc.tar.gz

Load the PLC Docker image.

Deploy the PLC Container.¶

Verify and deploy the container.

    docker image ls
    docker run -it --rm --device /dev/uio0 --network host altera-plc:arm64

The following image shows the IP address and port to interface with the PLC web-server.

"docker run" command output.

Launching the PLC Webserver and Running an ST file.¶

In a host machine withing the same network as the development kit, launch a web browser with the address that was shown in the console window (usually http://<dk-ip-address>:8080) and login. For example in Firefox:

Login into the OpenPLC webserver with:

username: openplc
password: openplc

OpenPLC Webserver interface login screen.

Load the Agilex Drive On Chip OpenPLC driver. In the OpenPLC Webserver, navigate to Hardware and select Agilex Drive-On-Chip OpenPLC Hardware Layer. Press the Save Changes button and let let the compilation finish (it can take a few minutes). When done, press the Go to Dashboard button at the bottom of the page.

Agilex™ Drive-On-Chip PLC driver selection.

In the OpenPLC webserver, navigate to Programs tab in the left panel, then press Browse and load agilex_doc.st file (see Binaries). Press the button Upload Program. Give the program a name, e.g. "doc-agilex" and press Upload Program button. Let the compilation finish (this can take a few minutes).

Structured Text (ST) PLC program load and compile.

Press the Go to Dashboard button to select the Dashboard tab and execute the .st program with the button Start PLC in the left panel. The PLC Controller will start to run and control the Drive On Chip system in the FPGA fabric.

Start the PLC-based Drive-On-Chip motion controller.

In the OpenPLC webserver, in the left panel, navigate to the Monitoring tab. This will show the dual axes of the "Drive On Chip" being controlled by OpenPLC and the PLCopen-based RTMotion Library according to the .st (structured text) program loaded previously.

OpenPLC Webserver Monitoring tab for Axis Control Visualization.

Create and run your own program:

You can create your own .st file and load it in the OpenPLC Programmable Logic Controller to modify the speed and/or position of any of the two drives in the FPGA systems (Dual Axis Drive-On-Chip)

Monitoring the DoC through JTAG interface.¶

The user can visualize the "Drive On Chip" (DoC) behavior using an independent JTAG channel. This channel shows the axes speed/position that is being requested by the PLC Controller. The "Drive On Chip" system exposes these (and other) values through JTAG chain that can be accessed with a GUI running in your local host. To visualize the DoC drive control characteristics follow these steps:

Keep the Altera® FPGA download cable and JTAG connection to the board.

Unzip the GUI source code, see Binaries:

unzip doc-gui_1.0.0.zip
cd <download>/doc-gui_1.0.0

Open a terminal, install the requirements (if needed) and run:

pip install -r requirements.txt
python __main__.py

Select the right JTAG master from the menu (if it is not selected automatically). Usually AE5(C0…0)...

Select the Agilex™ device in the JTAG Device dropdown menu.

When the GUI is running, change to the "Axis" tab, in the left panel. The tab shows the speed values of both Axis changing as it is shown in the OpenPLC webserver. To see more details, press the Start Trace button in the right-bottom of the GUI to display speed and position traces.

Drive On Chip GUI for visualization.

Warning

Do not change speed or position values in the Python GUI. The drives are being controlled by the PLC and the GUI should be only used for visualization purposes.

Recommended User Flows¶

With the available resources, you can build, compile, modify, and execute this design example. Additionally, there are two extra user flows that you can explore.

User Flow 1: Getting Started - Running with pre-build binaries.
User Flow 2: Running the example design using the QAR and KAS
User Flow 3: Running the example design by create/build Modular Design Toolkit (MDT) and KAS.

More resources.

Source	Link
Pre-created QAR file	DOC_PLC_TANDEM_MOTORSIM_AGILEX5.qar
JIC/RBF files	top.hps.jic top.core.rbf
u-boot-spl-dtb.hex	u-boot-spl-dtb.hex

Recommended User Flows.

User Flow	Description	User flow 1	User flow 2	User flow 3
Pre-requisites	Software Requirements to run.	✓	✓	✓
	Software Requirements to build.	✗	✓	✓
	Hardware Requirements.	✓	✓	✓
	Download the minimum Pre-built Binaries.	✓	✗	✗
HW-Compilation	Compile pre-created QAR with Quartus®.	✗	✓	✗
	Generating and Building the NiosV/g BSP for the Drive-On-Chip Application.	✗	✓	✗
	Creating and Building the Design based on Modular Design Toolkit (MDT).	✗	✗	✓
	Creating the QSPI Flash and SD card configuration bitstreams for the board (JIC/RBF).	✗	✓	✓
SW-Compilation	Create SD card image (.wic) using YOCTO/KAS NOTE: use KAS_MACHINE=agilex5_modular and kas_dual_axis.yml configuration	✗	✓	✓
	Altera OpenPLC Docker Container Image Cross-compilation. Optional	✗	*	*
Programming	Setting Up your Development Board.	✓	✓	✓
	Burn the SD card image.	✓	✓	✓
	Expand the SD card Root File System Partition.	✓	✓	✓
	Program the QSPI Flash Memory.	✓	✓	✓
Testing	Run the OpenPLC Docker Container.	✓	✓	✓
	Launching the PLC Webserver and Running an ST file.	✓	✓	✓
	Monitoring the DoC through JTAG interface.	✓	✓	✓

Example Design Documentation¶

Drive-On-Chip with PLC Design Example for Agilex™ 5 Devices