Getting Started

Owned by Tino Biehle
Last updated: Apr 22, 2024
6 min read

This page is intended to provide an initial overview of how to start developing with the System in Module (SoM). On this page you’ll find links to mandatory and useful Software, How-To’s and User Manuals.

We would recommend downloading the uGOAL Software Package and the Industrial Communication Explorer to use on of our Example Applications to get an quick Introduction into developing Applications for the SoM.

Hardware

The EVAL Kits provided by us contains the System on Module, an Arduino Adaptershield, an USB Cable and optionally an Application Controller of your Choice. The System is preconfigured and -flashed and, if an Application Controller is included, shall start the example Application iRJ45 / SoM - GOAL examples | 01_pnio_io_mirror, which is also included in the uGOAL Software Package.

System on Module EVAL Kit with Synergy S7G2-SK as Application Controller
System in Module EVAL Kit with STM32H755 as Application Controller

Software

Firmware for SoM

The Stack-on-Module or System-on-Module (SoM) is flashed with our Middleware called Generic Open Abstraction Layer (GOAL) and comes with several Industrial Protocol Stacks like Profinet, EtherNet/IP, EtherCAT, OPC-UA and Modbus TCP. We provide Firmware Updates with new Features or Bugfixes regularly to keep the SoM reliable and up-to-date.

The Firmware with OPC UA functionality is currently a seperated one.

som_2.2.0.0_ci23.pfw

Download:

Default Firmware for the SoM containing Profinet, EtherNet/IP, EtherCAT and Modbus TCP.

som_2.2.5.0b_ci49.pfw

Download:

Firmware containing the OPC-UA Protocol Stack.

 

How-To Update the Firmware with the Industrial Communication Explorer: Update with ICE

uGOAL Software Package

The uGOAL Software Package contains the whole Sourcecode for your desired Application Controller to configure and start Industrial Ethernet Protocols at the SoM. It also contains several Example Applications and Pre-Build Projects for IDEs like STM32CubeIDE, MCUExpresso, S32Designstudio or e2studio. Following Releases are available:

Download: 2015013_ugoal_release_2.2.5.zip

Please refer to following pages about the included components:

Industrial Communication Explorer

The free Industrial Communication Explorer (ICE) is an accompanying tool for all devices powered by the GOAL/uGOAL Device Detection protocol such as SoM/iRJ45 device and assists in developing applications on Windows, Linux and Mac OS.

The tool allows to configure the SoM, creating snapshots of the current state, update the firmware, read logs and initiate a PROFINET, EtherNET/IP or EtherCAT connection using the integrated master emulators.

Please refer to following pages about the Industrial Communication Explorer:

Industrial Communication Creator

For comfortable and easy configuration and object dictionary management, we’re providing our Industrial Communication Creator (ICC) which enables the user to develop communication solutions using port Industrial Ethernet Protocol Stacks like Profinet, EtherNet/IP or EtherCAT rapidly.

You’ll find demo versions here:

Necessary Plugins for creating SoM-specific applications are here:

You can aquire a full version of the Tool on following page: https://www.port.de/en/products/canopen/tools/canopen-design-tool.html

Please refer to following pages about the Industrial Communication Explorer:

Starting Developing

Pre-Requisites

We’re using an STM32F429zi EVAL Kit with SoM and the STM32CubeIDE for the next few steps - but the process is similiar to other Applications Controller (AC) and IDEs.

To starting developing for the STM32, you’ll need following:

  • Installed and working STM32CubeIDE,

  • Installed and working ICE,

  • optionally HTerm, to see Logging messages from the AC: HTerm

  • Downloaded uGOAL Software Package

Importing Project into STM32CubeIDE

Extract the downloaded uGOAL Software Package onto your hard drive. Please keep the path length as short as possible, as some Windows Versions allow a maximum path length of 255 chars.

Import a project (for instance “projects/ugoal/02_profinet”). Please refer to https://portgmbh.atlassian.net/wiki/spaces/IRJ45SOM/pages/201490466/STM32+uGOAL#Integration-into-STM32CubeIDEfor instructions.

Developing

As described at 004 - uGOAL - Introduction , the uGOAL Software Package take care of the Initialization, Configuration and the cyclic Communication of/with the SoM.

The file goal_appl.c (see image [1]) is the API to the user and usually contains the three functions [2]:

  • appl_init() - initialize local ressources in preparation for the industrial protocol stack,

  • appl_setup() - configure protocol stack, like vendor name, creates and starts appropriate protocol stack and creates objects and

  • appl_loop() - is called each millisecond by uGOAL to do cyclically tasks, like reading out sensors and put the values into the created objects [3].

Start HTerm and configure the Terminal as shown below. After Connecting to the right “Port” and Flashing the Application, the Output should look like this:

stm32 platform initialized<\n> ================================<\n> initial HEAP size: 192583 bytes<\n> [INF] D:/ugoal/rpc/goal_media/goal_mi_mctc.c:819 rpc transfer size set to 1024<\n> [INF] D:/ugoal/rpc/goal_media/goal_mi_mctc.c:747 peer requested Sync Init<\n> [INF] D:/ugoal/rpc/goal_media/goal_mi_mctc.c:747 peer requested Sync Init<\n> [INF] D:/ugoal/rpc/goal_media/goal_mi_mctc.c:747 peer requested Sync Init<\n> [INF] D:/ugoal/rpc/goal_media/goal_mi_mctc.c:747 peer requested Sync Init<\n> [INF] D:/ugoal/rpc/goal_media/goal_mi_mctc.c:471 RPC state synchronized, running appl_setup<\n> [INF] D:/ugoal/rpc/goal_media/goal_mi_mctc.c:474 configuring timeout values for peer<\n> [INF] D:/ugoal/rpc/wrapper/pnio/goal_pnio_rpc_ac.c:341 PROFINET Application Core successfully started<\n> [INF] D:/ugoal/projects/ugoal/02_profinet/goal_appl.c:252 Initializing device structure<\n> [INF] D:/ugoal/rpc/wrapper/pnio/goal_pnio_rpc_ac.c:4132 generic data provider mapped to position 0<\n> [INF] D:/ugoal/projects/ugoal/02_profinet/goal_appl.c:309 PROFINET ready<\n> [INF] D:/ugoal/rpc/goal_media/goal_mi_mctc.c:506 local setup done<\n> !! application setup done !!<\n> HEAP remaining free: 188775 bytes<\n>

… And where do I have to put my Code?

As mentioned in the previous chapter, the files goal_appl.c/h and goal_config.h should be extended with your code and configuration.

Application

See following example application for some Inspiration, which reads out a temperature sensor - using the HAL (Hardware Abstraction Layer) for STM32 Targets provided by STM32CubeID - each second and put this data into a created Profinet Submodule:

#include "stm32f4xx_hal.h" extern ADC_HandleTypeDef hadc1; /**< ADC handle from HAL */ GOAL_STATUS_T appl_setup( void ) { HAL_StatusTypeDef result = HAL_ERROR; /* result from HAL */ /* configure and start PROFINET */ ... /* TODO: put here your code for configuration of hardware for instance, * this function is called once the cyclic communication with the SoM is * established */ ... }
void appl_loop( void ) { GOAL_STATUS_T res; /* result */ static GOAL_TIMESTAMP_T tsTout; /* last timestamp */ uint32_t adcvalue_U32 = 0; /* value read from ADC */ /* read out sensor if AR is established and timeout is passed */ if ((GOAL_TRUE == flgAppReady) && (goal_timerTsGet() > tsTout)) { /* set new timeout of 1 second */ tsTout = goal_timerTsGet() + 1 * GOAL_TIMER_SEC; /* read ADC for temperature of connected sensor */ adcvalue_U32 = HAL_ADC_GetValue(&hadc1); /* TODO: conversion to real temp. depends on used hardware */ adcvalue_u32 = appl_adcTempConvertion(adcvalue_U32); /* put value into submodule */ if (0 != adcvalue_U32) { res = goal_pnioDataInputSet(pPnio, APPL_API, APPL_SLOT_1, APPL_SLOT_1_SUB_1, (char *) &adcvalue_U32, sizeof(adcvalue_U32), GOAL_PNIO_IOXS_GOOD); } if (GOAL_RES_OK(res)) { goal_logInfo("temperature read from ADC: %"FMT_u32"", adcvalue_U32); } } }

Configuration

The file goal_config.h contains defines to configure uGOAL. You'll find the frequently used ones at the goal_config.h of the example applications. The default values are set at the file ugoal/ugoal_default.h and most of the defines are over-writeable - you can re-define it at your goal_config.h.

For developement purposes you might want to set breakpoints at your STM32CubeIDE project to take a further look at variables and the uGOAL state. Per default this would lead to an aborted SPI connection between the application controller and the SoM, as uGOAL is halted and cannot process any received SPI-Frames. The SoM would detect this and transit into an error-state.

To disable the peer-loss detection and the mentioned behavior add the following define to the goal_config.h of your application: