004 - uGOAL - Introduction

Changelog

Version

Changes

Version

Changes

1.0

Initial version

1.1

Clarification of naming

1.2

List of components and examples

Introduction

uGOAL describes a software package, which allows integration of the irj45/SoM 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. Most GOAL functionality is not available, however the CCM specific examples for fieldbus applications can be reused mostly without adaption.

Components

uGOAL contains a core which includes the basic GOAL framework functionality required for Remote Procedere Call (RPC) wrappers. Following RPC wrappers are available for uGOAL:

RPC wrapper

functionality

remarks

RPC wrapper

functionality

remarks

pnio

Profinet Stack

fully supported

ecat

EtherCAT Stack

fully supported

eip

EtherNet/IP Stack

fully supported

http

Web Server

only recommended on targets with > 32kByte RAM available

net

UDP and TCP channels

only recommended on targets with > 32kByte RAM available

ccm

ccm module management

fully supported

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: https://portgmbh.atlassian.net/wiki/spaces/IRJ45SOM/pages/169508866.

Examples

Many examples are available:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 projects 2├── 2015013_irj45 3│ ├── 01_pnio_io_mirror 4│ ├── 02_eip_io_data 5│ ├── 04_pnio_validation 6│ ├── 05_pnio_01_simple_io 7│ ├── 06_eip_io_data_static_ip 8│ ├── 07_pnio_dsn 9│ ├── 08_pnio_01_simple_io_http 10│ ├── 09_ecat_slave 11│ ├── 10_pnio_process_alarm 12│ ├── 11_firmware_update 13│ ├── 12_ecat_validation 14│ ├── 13_firmware_update_callback 15│ ├── 14_ip_management 16│ └── 15_tcp_proxy 17├── goal_http 18│ ├── 01_get 19│ ├── 02_post 20│ ├── 03_list_res 21│ ├── 04_auth 22│ ├── 05_template_cm 23│ ├── 06_template_list 24│ └── 07_template_table 25├── goal_net 26│ ├── 01_udp_receive 27│ ├── 02_tcp_client 28│ └── 03_tcp_server 29└── ugoal 30 ├── 01_ethercat 31 ├── 02_profinet 32 ├── 03_eip 33 ├── 04_profinet_dyn_modules 34 ├── 05_ccm 35 ├── 06_ethercat_minimal 36 ├── 07_http_ip_management 37 ├── 08_pnio_io_mirror 38 └── 09_pnio_io_mirror_new_api

 

Examples from the 2015013_irj45 folder are derived from GOAL based examples. Additional description can be found here: https://portgmbh.atlassian.net/wiki/spaces/IRJ45SOM/pages/169312303.

Examples under the goal 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: https://portgmbh.atlassian.net/wiki/spaces/IRJ45SOM/pages/171704363.

Platform porting

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

Function

Signature

Remark

Function

Signature

Remark

plat_init

1 2 3 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

plat_spiTransfer

1 2 3 4 5 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 CCM module. The response data needs to be propagated into the rxBuf buffer. Only the amount of data (size) is allowed to write into rxBuf.

This function is called cyclically by the uGOAL framework.

plat_ledSet

1 2 3 int plat_ledSet( uint32_t state /**< led state field */ );

This function can be used to set LED states acquired from the CC module, which may be required for some fieldbus protocol implementations.

plat_heapAllocDone

1 2 3 void plat_heapAllocDone( void );

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

plat_getMsTimer

1 2 3 GOAL_TIMESTAMP_T plat_getMsTimer( void );

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.

plat_eventRegister

1 2 3 4 int plat_eventRegister( GOAL_BOOL_T flgAutostart, GOAL_MA_EVENT_NOTIFY fNotify )

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

plat_eventEnable

1 2 3 int plat_eventEnable( void )

Enables the configured events.

plat_eventDisable

1 2 3 int plat_eventDisable( void )

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.