004 - uGOAL - Introduction
Changelog
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 |
---|---|---|
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: iRJ45/SoM - User Manual.
Examples
Many examples are available:
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: iRJ45 / SoM - GOAL examples.
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: iRJ45 / SoM - uGOAL Examples.
Platform porting
The platform interface required for integration into an platform contains of the following functions:
Function | Signature | Remark |
---|---|---|
plat_init | void plat_init(
void
); | This function is called upon start of the application. It is required to initialize the required hardware peripherals here:
|
plat_spiTransfer | 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 | 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 | This function is called when dynamic memory allocation is done. It can be used to evaluate the memory utilisation. | |
plat_getMsTimer | 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 | 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 | Enables the configured events. | |
plat_eventDisable | 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 |
---|---|---|
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. |
Â