004 - uGOAL - Introduction

Owned by Torsten Bitterlich (Unlicensed)
Last updated: Oct 24, 2024 by Tino BiehleVersion comment
5 min read

Introduction

uGOAL describes a software package, which allows integration of the System-on-Module into applications without using a full GOAL framework platform. By stripping down the required dependencies from the GOAL industrial communication framework, integration is possible into a wide range of platforms from a simple ATMEGA 8-bit CPU with 2KB of RAM up to a linux PC.

uGOAL mimics the required functionality from the GOAL framework specifically needed by the application controller framework. It is configurable in different ways to ensure compatibility with a wide range of targets. Some of the GOAL functionality is not available, however the CCM specific examples for fieldbus applications can be reused mostly without adaption.

Components

Following table shows which features are available for uGOAL and GOAL.

Feature

Remark

GOAL

uGOAL

Feature

Remark

GOAL

uGOAL

GOAL core framework

Basic GOAL core functionally as:

  • Timers

  • Tasks

  • Semaphores

RPC wrapper functionality

RPC wrappers for:

  • EtherCAT with CoE, EoE, FoE and DC

  • PROFINET

  • EtherNet/IP

  • Modbus TCP

  • HTTP

  • TCP/UDP channels

  • CCM manangement functions

API

The uGOAL based software delivery is API compatible with the GOAL based software delivery. Therefore all existing application and examples can be reused with minimal adaption. Thus the communication module user manual also applies to the uGOAL software delivery: iRJ45/SoM - User Manual.

Examples

Many examples are available:

projects ├── 2015013_irj45 │   ├── ac │   │   ├── 01_pnio_io_mirror │   │   ├── 02_eip_io_data │   │   ├── 04_pnio_validation │   │   ├── 05_pnio_01_simple_io │   │   ├── 06_eip_io_data_static_ip │   │   ├── 07_pnio_dsn │   │   ├── 08_pnio_01_simple_io_http │   │   ├── 09_ecat_slave │   │   ├── 10_pnio_process_alarm │   │   ├── 11_firmware_update │   │   ├── 12_ecat_validation │   │   ├── 13_firmware_update_callback │   │   ├── 14_ip_management │   │   ├── 16_pnio_io_mirror_mrp │   │   ├── 17_mbtcp_simple_io │   │   ├── 18_opcua_basic │   │   └── 19_opcua_extended ├── goal_eip_rpc │   ├── 01_simple_io │   ├── 02_dlr_dhcp │   ├── 03_dhcp │   ├── 04_parameter │   ├── 05_acd_dhcp │   └── common ├── goal_http_rpc │   ├── 01_get │   ├── 02_post │   ├── 03_list_res │   ├── 04_auth │   ├── 05_template_cm │   ├── 06_template_list │   └── 07_template_table ├── goal_net_rpc │   ├── 01_udp_receive │   ├── 02_tcp_client │   └── 03_tcp_server ├── goal_pnio_rpc │   ├── 01_simple_io │   ├── 02_io_demo │   ├── 03_record_write │   ├── 05_ioxs_states │   ├── 06_apdu_status │   ├── 07_alarm_button │   ├── 08_dynamic_modules │   ├── 09_busy_records │   ├── 10_led_demo │   ├── 11_multiple_write │   ├── 12_diag_entry │   ├── 13_pnio_snmp │   ├── 14_info_set │   ├── 15_config_set │   ├── 16_device_name │   ├── 17_process_alert │   ├── 18_dyn_mod_postpone │   ├── 19_subst_val │   ├── 21_pnio_snmp_dm │   ├── 22_process_alarm_buf │   ├── 24_pnio_snmp_mrp │   ├── 25_dynamic_modules_dm │   └── gsdml ├── icc │   ├── ecat_106 │   ├── ecat_64byte │   ├── ecat_cia402 │   ├── ethercat │   ├── ethernetip │   ├── pnio_32modules │   ├── pnio_iomodule │   ├── pnio_slot2 │   └── profinet ├── ugoal │   ├── 01_ethercat │   ├── 02_profinet │   ├── 03_eip │   ├── 04_profinet_dyn_modules │   ├── 05_ccm │   ├── 06_ethercat_minimal │   ├── 07_http_ip_management │   ├── 08_pnio_max_data_rpc │   ├── 09_pnio_io_mirror_new_api │   ├── 10_ethercat_rpc │   └── 11_eip_rpc

Examples from the 2015013_irj45 folder are derived from GOAL based examples. Additional description can be found here: iRJ45 / SoM - GOAL examples.

Examples under the ugoal folder are developed with uGOAL in scope, thus they are generally more suitable for smaller targets (up to only 8kByte of RAM). Additional description can be found here: iRJ45 / SoM - uGOAL Examples.

Platform porting

The platform interface required for integration into an platform contains of the following functions:

Signature

Remark

Signature

Remark

void plat_init( void );

This function is called upon start of the application. It is required to initialize the required hardware peripherals here:

  • SPI

  • Timer

  • I2C (optional)

  • Memory HEAP

int plat_spiTransfer( const char *txBuf, /**< [in] transmission buffer */ char *rxBuf, /**< [out] receive buffer */ int size /**< size of valid buffer sizes */ );

This function needs to transfer the given data (txBuf) with a length of size to the System-on-Module. The response data needs to be propagated into rxBuf. Only the amount of data (size) is allowed to write into rxBuf.

This function is called cyclically by the uGOAL framework.

This function can be used to set LED states acquired from the System-on-Module, which may be required for some fieldbus protocol implementations.

This function is called when dynamic memory allocation is done. It can be used to evaluate the memory utilisation.

This function needs to return the number of milliseconds from start of the system. It is needed for timed operations and timeouts.

Following optional functions are necessary to support EtherCAT DC.

Signature

Remark

Signature

Remark

This optional function registers a callback function for external interrupts used e.g. for EtherCAT DC. It also initializes the interrupts configured in the specific platform.

Enables the configured events.

Disables the configured events.

Multitasking

The software delivery does not specifically consider issues of multi tasking systems. Thus if one wants to integration the code into a multitasking application, all uGOAL relevant functions should be concentrated and called from one single task. Data exchange with other tasks should be done in a protected way (locking, messages, semaphores, queues). This is not scope of the software delivery.

Configuration

Following table shows the most important configuration options of the software. Those are defined with a default value in ugoal/ugoal_default.h.

Configuration

Default value

Description

Configuration

Default value

Description

CONFIG_UGOAL_HEAP_BUFFER

0

By default uGOAL uses malloc for initial memory allocation. It can be forced to use a statically allocated buffer for initial memory allocation, if e.g. the underlying platform does not provide such functionality. In each case, behaviour will be the same. Only initially memory is allocated. During runtime of the application memory is static.

CONFIG_UGOAL_HEAP_BUFFER_ALIGNMENT

0

With this option allocated memory hunks can be forced to a specific alignment. This may be useful for platform specific adoption.

CONFIG_UGOAL_HEAP_BUFFER_SIZE

0

If the static memory buffer is enabled, with this option the size of the buffer needs to be defined.

CONFIG_UGOAL_DATAMAPPER

0

The data mapper provides an abstraction of the cyclic data channel. If enabled, the RPC stack wrappers will map process data to this entity. Thus access to process data is convenient. Without the data mapper process data needs to be accessed within the raw SPI frame. Usage of the data mapper costs some memory.

CONFIG_UGOAL_TIMEOUT_RPC

5000

This is the time (in milliseconds) before a RPC request is considered to be timed out. For debugging purpose this value may be set to 0, so a pause in execution of the application does not lead to communication errors. For production purpose this value is not allowed to be 0.

CONFIG_UGOAL_TIMEOUT_MEDIA

1000

This is the time (in milliseconds) before missing communication on the SPI is considered to be a fault. For debugging purpose this may be set to 0, so a pause in execution of the application does not lead to communication errors. For production purpose this value is not allowed to be 0.

CONFIG_UGOAL_INSTANCE

1

This option enables the optional support for instances of components in UGOAL. The data mapper and HTTP requires and automatically enables this feature. Otherwise it is not required, since it costs some memory.

CONFIG_UGOAL_MAINLOOP_REG

1

This option enables support for registration of cyclic functions during the execution of the application. The data mapper requires and automatically enables this feature. Otherwise it is not required, since it costs some memory.

CONFIG_UGOAL_LOGGING

0

This option enables UART logging.

CONFIG_UGOAL_RPC_RB_SIZE

274

This option configures the size of an entry within the RPC ring buffer. It defines the maximum size of a RPC request. This value is optimized for memory footprint. Some applications may require larger values, if e.g. larger amounts of data are transported via RPC.

CONFIG_UGOAL_RPC_RB_ENTRIES

1

This option configures the length of the ring buffer in chunks of CONFIG_UGOAL_RPC_RB_SIZE.

CONFIG_UGOAL_RPC_HANDLES

2

This option configures the amount of available RPC handles. Each component (e.g. a communication Stack wrapper) requires a handle. One handle is allocated by the base system.