X-LINUX-IGTW1 V1.0.0 Linux Package

1. Introduction

The X-LINUX-IGTW1 is a Linux-based expansion software package designed for industrial application development on STM32MP and other microprocessor platforms. It provides drivers, APIs, and applications tailored for the X-STM32MP-IGTW1 board, which features CAN Bus and RS485 interface along with STSAFE, EEPROM, RS232, RTC, STMOD+. This package serves as a foundational tool for engineers to build industrial solutions.

PACKAGE TOP DIR
├── x-linux-igtw1_build.sh
├── meta-st-stm32mp-igtw1
├── x-linux-igtw1_init_build.sh
├── x-linux-igtw1_conf_append.txt
├── NUCLEO-C092RC/
├── board_pin_mapping.md
├── README_Hardware_Test_Suite.md
├── README_IGTW1_App.md
├── README_Hardware_Test_Suite.md
└── README.md

2. Software Features

The X-LINUX-IGTW1 package includes a range of features for Industrial application development:

1. Node-Red web demo application for network based remote control or monitoring using RS485 and CAN Bus nodes.
2. Python based GUI test application to test onboard peripherals.
3. Driver support for RS232/RS485, CAN Bus, EEPROM, RTC, STMOD+.

3. X-LINUX-IGTW1 Architecture

The package is composed of multiple layers and modules:

3.1. Hardware Drivers and APIs

• Kernel and device tree patches included in the package to enable CAN Bus,EEPROM, RS232/RS485, RTC, STMOD+.

3.2. Applications

Includes two sample applications.

• Python based GUI application to test all peripheral individually
• Node-Red based application, which is a browser-based editor that allows users to drag and drop nodes to create flows. These flows can be deployed with a single click, making it highly user-friendly. one sample flow is shared in release.

Engineers can develop custom applications leveraging the APIs and drivers provided in this package.

4. Hardware Components and Setup

The current package provides software support for [X-STM32MP-IGTW1] expansion board.

Key STMicroelectronics components available on this board are described below:

• ST4E1240: A high-speed RS-485 transceiver supporting data rates up to 20 Mbps, operating from 3.0 to 5.5 V. It features low-power consumption (1.5 mA active,<1 μA shutdown), integrated ESD protection, and fail-safe mechanisms for reliable communication in industrial applications.
• ST3232C: A dual RS-232 transceiver operating from 3.0 to 5.5 V, supporting data rates up to 400 kbps. It features integrated charge pump capacitors and has low-power consumption (1 μA in shutdown).
• M41T83: a real-time clock (RTC) with a built-in battery backup, providing accurate timekeeping for embedded systems. It operates from 1.8 to 5.5 V, features a low-power consumption of 1 μA in battery mode, and includes programmable alarms, a watchdog timer, and a 32.768 kHz output for precise timing applications
• STSAFE-A110: A secure element on the board that provides hardware-based authentication and cryptographic services, ensuring data integrity and confidentiality for IoT devices and peripherals.
• M24C32-R: A 32-kbit EEPROM with I²C interface, providing nonvolatile memory for data storage, ideal for industrial applications requiring reliable data retention and easy integration.
• [CAN transceiver]: high-speed CAN transceiver designed for reliable communication in automotive and industrial applications, providing robust data transmission with data rate up to 1 Mbps and reception with low-power consumption, ±36 VBUS fault tolerance, excellent noise immunity and includes autobaud loopback.

The X-STM32MP-IGTW1 board can be plugged into the 40-pin connectors available on STM32MP discovery boards or Raspberry Pi, as shown below.

4.1. Important Setup Notes

• Ensure correct board orientation when mounting on platforms like STM32MP discovery kits or Raspberry Pi. For example, the board mounts "outward" on STM32MP257F-DK boards.
• Verify jumper settings for the X-STM32MP-IGTW1 to operate in either RS232 or RS485 mode. (NOTE: Sample application are based on RS485, make sure to connect jumpers in correct location as shown below).

5. Software Setup

This section describes the software setup required for building, flashing, deploying, and running the application.

5.1 Recommended PC Prerequisites

A Linux® PC running Ubuntu® 22.04 or higher is recommended. Developers can follow the link below for details: PC prerequisites.

5.2 Integrating X-LINUX-IGTW1 into Distribution build

After making sure PC Prerequisites are met, Automation init and build scripts can be run.

Shell script "x-linux-igtw1_init_build.sh" does Initialization of Distribution build and Integration for stm32mp257f-dk and x-stm32mp-igtw1 pair. Follow below steps:

1. Download and Copy X-LINUX-IGTW1
2. add execute permissions

$chmod +x x-linux-igtw1_init_build.sh 

3. execute X-LINUX-IGTW1 init and build script x-linux-igtw1_init_build.sh

./x-linux-igtw1_init_build.sh

( Build directory can be manually set after modifying build,layer paths macro in "x-linux-igtw1_init_build.sh" and "x-linux-igtw1_build.sh" scripts )

NOTE:Repo can be downloaded manually and use automation script as long as its based on 6.x ecocsystem

Follow the instructions on the ST wiki page Distribution build to prepare the Distribution package build environment. X-LINUX-IGTW1 can be integrated into the distribution package build environment.

5.3 Deploying the Files to the MPU Board

Once the build is completed, follow Flashing steps mentioned below.

There are two ways to flash the generated images.
5.3.1) Using STM32CubeProgrammer:
Refer to below links:

Flashing the built Image Boot modes STM32MP257F-DK
Note:

use optee file: FlashLayout_sdcard_stm32mp257f-dk-optee.tsv

5.3.2) using shell scripts present in build folder.

Make sure to have SD Card reader, connect SD Card (minimum 16GB)

Connect SDcard to Linux Host machine where Distribution build was done.

assume SDcard is /dev/sdX (where X can be a,b,c ...)

NOTE: One can check and find X value by unplugging and plugging, checking sudo dmesg command.

** 5.3.2.1) Go to Image build directory, create and flash raw image using below commands **

Go to Image build dir

$cd build-openstlinuxweston-stm32mp2/tmp-glibc/deploy/images/stm32mp2/

Generate raw image for flashing

$./scripts/create_sdcard_from_flashlayout.sh flashlayout_st-image-qt/optee/FlashLayout_sdcard_stm32mp257f-dk-optee.tsv

NOTE: running will ask for replacing older image, either take backup or if not needed, replace by typing Y

Reference logs below

[WARNING]: A previous raw image are present on this directory

[WARNING]: flashlayout_st-image-qt/optee/../../FlashLayout_sdcard_stm32mp257f-dk-optee.raw

[WARNING]: would you like to erase it: [Y/n]

Y <--- Enter Y to replace.

5.3.2.1) Flash Raw image Generated

NOTE: BE Careful!!!, wrong sdX value can wipe out complete Host OS

NOTE: Replace sdX with appropriate value (ex. sdb , sdc etc.)

$sudo umount /dev/sdX*
$sudo dd if=./FlashLayout_sdcard_stm32mp257f-dk-optee.raw of=/dev/sdX bs=8M conv=fdatasync status=progress  

6. Installing IGTW1 Application Prequisites (one-time, after first boot)

After Flasing, Insert SD-Card in STM32MP257F-DK2, and boot. (Check STM32MP257F-DK2 page for Boot switches state for SD-Card Boot,Boot modes STM32MP257F-DK After boot, run Post-installation script via terminal.

$su
#cd /usr/gateway_demo
#./post_install_IGTW1.sh

Once installation is done, reboot

#reboot

NOTE: Make sure Internet is availaible on MP2 Board.otherwise script will exit with warning as shown below

7. Running IGTW1 Applications

Follow README_IGTW1_App.md present in package.

8. Notes on Compatibility

• scripts and files present in release package are platform-dependent and are provided for specific MPU boards. Customization may be necessary for other platforms.
• If kernel customization is needed, refer to How to Customize the Linux Kernel.
• On STM32MP boards, some GPIOs available on the 40-pin header are shared with other peripherals. To ensure exclusive access to the 40-pin header, certain solder bridges may need to be opened or closed. Refer to user manual of the specific MPU board. Also, look into the board_pin_mapping.md file of the package for more information.

8.1 Compatibility Information

The X-LINUX-IGTW1 software package is validated for OpenSTLinux version 6.1. Running it on other ecosystem versions may require additional configuration. The software is tested on the following boards:

1. STM32MP257F-DK

9. License

Details about the terms and conditions of use for the various components are available in the LICENSE.md file.

10. Release Notes

The content and changes included in this release are documented in the Release Notes.

11. Related Information and Documentation

Here are additional resources related to the X-LINUX-IGTW1 package and its supported hardware:

• X-STM32MP-IGTW1 Expansion Board
• STM32MP257F-DK Board