Application

Introduction


This document provides information about how to build an application for the irj45 communication module.

Hardware setup


The module provides a management inferface, where initial configuration can be done. These properties can be stored permanently within the device. Following properties are provided to configure the SPI interface:

Variable

Description

Default value

SPI_TYPE

SPI master/slave configuration

1 = SLAVE

SPI_MODE

SPI timing mode

0 = MODE0

SPI_UNITWIDTH

SPI single transfer size

0 = 8 BIT

SPI_BITORDER

SPI bit transfer direction

0 = MSB

SPI_TRANSFERSIZE

SPI packet transfer size

128

Table 3 SPI configuration
The module does only support SPI_TYPE slave.
The module does only support SPI_UNITWIDTH of 8 bit.
The module does only support SPI_TRANSFERSIZE of 128 byte.
The SPI mode can be configured according to Table 4.
The SPI bitorder can be configured according to Table 5.

Value

SPI MODE

0

Mode 0

1

Mode 1

2

Mode 2

3

Mode 3

Table 4 SPI Mode configuration

Value

SPI BITORDER

0

MSB

1

LSB

Table 5 SPI bitorder configuration

Basic application setup


A basic application consists of the optional function calls appl_init, appl_setup and appl_loop. It follows the design philosphy of the GOAL middleware.

Default Features


By default, the irj45 CC module will start a web server (on port 8080) for the firmware update feature and an instance of Device Detection for management using the management tool.
It is not possible by an AC application to disable the web server on the CC. However, the AC can start another instance of the web server.
It is possible for an AC application to limit the by default full management access through Device Detection in different ways. Please refer to the corresponding chapter in the documentation.

Features

Device Detection

Initial state


On the irj45 communication module DD is enabled by default. This allows full access to all variables and logs on the CC module. DD bases on a simple UDP based protocol with no encryption. Thus, an application can and should limit the access to a feasable range. Limitation of features and access is possible on various levels.

Initial disabling of features by the application


This property is applied at application startup when the AC application setup is executed. With the call of goal_ddNew() from appl_setup() a bitmask can be passed whith bits representing single functions of DD. Please refer to the API documentation of DD for possible values. If all bits are set, all features (hello, get, set, get_list, wink) are enabled.

Initial disabling of features by CM variable


The in chapter 4.5.1.2 described mechanism can also be set before application start by setting the corrensponding CM variable FEATURE_DISABLE (see chapter 4.9.1). Each request processed by the device detection module will utilize the value of this variable to determine, if the request is allowed to be processed.

Please note, that any call of goal_ddNew will overwrite the value of this variable, if a different initialization value is passed.

Temporary enable features of the device detection

 

This property is applied at an arbitraty time, for example when configured using a web site provided by the AC application.

GOAL_STATUS_T goal_ddSessionFeatureActivate(       GOAL_DD_T *pHdlDd, /*< dd handle */       uint32_t bitmaskFeatures                    /*< bitmask with feature enable bits set */   );  
  • The parameter bitmask contains bits representing features being enabled

  • Those bits overwrite the disable bits from CM for the current session

Filtering and access rights


This property is applied at starup of the AC application.

Using filters it is possible to limit access to CM variables by groups (module ids) and variables (variable ids). Currently some filters are predefined for usage. These can be enabled using following function:

GOAL_STATUS_T goal_ddFilterAdd(       GOAL_DD_T *pHdlDd,                          /*< dd handle */       GOAL_DD_ACCESS_FILTER_SET_T setId           /*< set id */ );

  
This function works on a created instance of DD, thus requires passing of a valid DD handle. The setId can be used with following values:

Set Id

Description

GOAL_DD_ACCESS_FILTER_SET_ALL

Complete access to all variables

GOAL_DD_ACCESS_FILTER_SET_BASIC

Filter for minimal
function of the management tool

GOAL_DD_ACCESS_FILTER_SET_HIDDEN

Filter for hiding critial information

Table 6 DD Filter IDs
Please refer to the API documentation of DD for detailed information.

PNIO


The communication module contains a full featured PROFINET slave stack. For application see the proper PROFINET documentation.

EtherNet/IP


The communication module contains a full featured EtherNet/IP slave stack. For application see the proper EtherNet/IP documentation.

EtherCAT


The communication module contains a full featured EtherCAT slave stack. For application see the EtherCAT stack documentation.

HTTPD


The communication module contains a web server for basic management functionality. Please refer to the proper HTTPD documentation as part of the GOAL - Programmer’s Manual.

Network channels


The communication module provides TCP and UDP communication channels. Please refer to the API documentation within this document for detailed description.

Generic Data Provider


For fieldbus communication applications a generic data provider is available, which contains gneralized information and led status for the application.

Data Provider Information

PROFINET

EtherNet/IP

EtherCAT

GOAL_MCTC_DP_STATUS_FLG_CONN

Connection

Connection

Connection (ESM-State == OP)

GOAL_MCTC_DP_STATUS_FLG_ERR

Error

Error

Application Layer Error

GOAL_MCTC_DP_STATUS_FLG_VALID

-

Process data valid

Process data valid









GOAL_MCTC_DP_LED_WINK

DCP blink signaling

-

-

GOAL_MCTC_DP_LED_RED1

Error

Module Status red

EC ERR Led May be configured to a STATUS Indicator, wher only LED_GREEN1 and LED_RED_1 are used.

GOAL_MCTC_DP_LED_RED2

Maintainance

Network Status red

(optional: part of the STATUS indicator)

GOAL_MCTC_DP_LED_GREEN1

Connection

Module Status green

EC RUN Led

GOAL_MCTC_DP_LED_GREEN2

DCP blink signaling

Network Status green

-

Table 7 MCTC Status information
The LED status information are a recommendation regarding conformance/usability of a device implementation. The delivered examples show usage of this feature.

Ethernet Startup Delay


With integration of EtherCAT in version 2.0.0.0 of the ccm module, an additional functionality was integrated which allows a dedicated startup of the network by the application controller. Depending on the chosen communication stack (e.g. PROFINET or EtherCAT), the network interface is brought up in the required mode.

A ccm module without an application controller however would never start the network in this scenario. Thus a fallback was implemented, which by default brings up the network after 5 seconds after startup of the ccm module. This behaviour can be configured using a ccm variable (module id 72, variable id 13).
Following table shows configuration options:

Timeout value

function

0

default timeout enabled (5 seconds)

1 ... 254

value determines timeout in seconds

255

timeout disabled

Table 8 ethernet timeout configuration
If powering of the application controller and establishing of the communication between AC and CC take longer then the configured timeout, it needs to be increased.

External Reset


The module provides an external reset input, where the AC can perform a reset of the irj45 module.

Do not perform this reset during a firmware update of the CC. This will prevent proper update functionality.

Therefore, it is recommended to utilize this reset only if the AC module is initially powered up (cold start).

RPC Synchronization reset


If either AC or CC restart, the peer module is required to restart too. Else a repeatedly RPC synchronization is not possible.

CC


By default, the CC module does not perform a reset implicitly. If the AC application restarts, a power cycle of the CC module (or a manual reset) is required. It is possible to configure this behaviour using the CM variable interface (see chapter 4.9.10).

AC


The AC performs a reset of it's application on request of the CC, e.g. when the CC restarts. This can happen during a firmware update.

IP Settings


IP Settings can be done with the CM interface.

Step

Action

Remark

1

Set CM Variable GOAL_ID_NET:IP

Configure IP address

2

Set CM Variable GOAL_ID_NET:NETMASK

Configure Netmask

3

Set CM Variable GOAL_ID_NET:GW

Configure Gateway

4

Set CM Variable GOAL_ID_NET:Valid to 1

Set IP configuration to valid

5

Set CM Variable GOAL_ID_NET:DHCP_ENABLED to 0

Disable DHCP

6

Set CM Variable GOAL_ID_NET:COMMIT to 1

Apply IP settings

Table 9 IP configuration with CM
To enable DHCP set the CM Variable GOAL_ID_NET:DHCP_ENABLED to 1 and perform a power cycle.

Management Interface CC


See goal_db, Page "Variables": The column "Long description" contains documentation of single variables. The management interface has following functions:

  • Responding to scan requests for devices

  • Listing CM variables

  • Reading CM variables

  • Writing CM variables

  • Setting IP address

  • Wink command

Each of those functions can be permanently disabled by setting a bit in the CM variable GOAL_ID_DD:FEATURE_DISABLE.

Management Interface DD


Module Id = GOAL_ID_DD (34)

MODULENAME

0

GOAL_CM_STRING

20

Customer specific name of the module

CUSTOMERID

1

GOAL_CM_UINT32

4

Customer Id

RESERVED

2

GOAL_CM_UINT8

1

-

FEATURE_DISABLE

3

GOAL_CM_UINT32

4

Each bit disables a function: bit 0, disable "HELLO DETECTION"bit 1, disable WINKbit 2, disable GETLISTbit 3, disable GET VALUEbit 4, disable SET VALUE

Table 10 DD management interface

PNIO

Module Id = GOAL_ID_PNIO (27)

  • Internal variables used by the Profinet stack

LM


These variables provide an interface for the logging manager of the irj45 module.
Module Id = GOAL_ID_LM (35)

Variable Name

Variable ID

Type

Max. Size

Long description

VERSION

0

GOAL_CM_UINT8

1

Version information for LM interface

READBUFFER

1000

GOAL_CM_GENERIC

128

Buffer for reading online logging from deivce

CNT

1001

GOAL_CM_UINT16

2

Control word for online log access

EXLOG_READBUFFER

1002

GOAL_CM_GENERIC

128

Buffer for reading exception logging from deivce

EXLOG_CNT

1003

GOAL_CM_UINT16

2

Control word for exception log access

EXLOG_SIZE

1004

GOAL_CM_UINT32

4

Indicator for exception log size

EXLOG_USAGE

1005

GOAL_CM_UINT8

1

Indicator for exception log usage

EXLOG_ERASE

1006

GOAL_CM_UINT8

1

Command:*, Erase Exception Log

Table 11 LM Management interface

NET


Module Id = GOAL_ID_NET (12)

Variable Name

Variable ID

Type

Max. Size

Long description

IP

0

GOAL_CM_IPV4

4

IP address of first interface

NETMASK

1

GOAL_CM_IPV4

4

NETMASK of first interface

GW

2

GOAL_CM_IPV4

4

GATEWAY of first interface

VALID

3

GOAL_CM_UINT8

1

Validity of IP address:0, Stored IP address is not valid, interface settings originate from network stack of system1, Stored IP address is valid, will be applied to interface at start of device

DHCP_ENABLED

4

GOAL_CM_UINT8

1

DHCP enable:0, DHCP disabled1, DHCP enabled

DHCP_STATE

5

GOAL_CM_UINT8

1

DHCP state:0, DHCP initialized1, DHCP server selecting2, DHCP requesting configuration3, DHCP ip address bound4, DHCP renewing configuration5, DHCP rebinding ip address to interface

DNS0

6

GOAL_CM_IPV4

4

First DNS server of first interface

DNS1

7

GOAL_CM_IPV4

4

Second DNS server if first interface

HOSTNAME

8

GOAL_CM_STRING

20

Hostname of first interface

COMMIT

1000

GOAL_CM_UINT8

1

Command:*, Apply IP settings

Table 12 NET Management interface

BOOT


Module Id = GOAL_ID_BOOT (37)

Variable Name

Variable ID

Type

Max. Size

Long description

SIGNATURE

0

GOAL_CM_GENERIC

16

Signature of booted image

BLVERSION

1

GOAL_CM_STRING

16

Bootloader Version

FWVERSION

2

GOAL_CM_STRING

16

Firmware Version

RESET_CAUSE

1000

GOAL_CM_UINT8

1

Reset cause:0, Unspecified1, Firmware Update Requested2, Watchdog3, Firmware Commit Required4, Reserved

IMAGE_NUMBER

1001

GOAL_CM_UINT8

1

Booted image number

IMAGE_COUNTER

1002

GOAL_CM_UINT8

1

Booted image age counter

Table 13 BOOTLOADER Management interface

CM


Module Id = GOAL_ID_CM (2)

Variable Name

Variable ID

Type

Max. Size

Long description

VERSION

0

GOAL_CM_UINT32

4

Version information for CM interface

SAVE

1000

GOAL_CM_UINT8

1

Command:*, Save CM to Flash

Table 14 CM Management interface

ETH


Module Id = GOAL_ID_ETH (4)

Variable Name

Variable ID

Type

Max. Size

Long description

MAC

0

GOAL_CM_GENERIC

6



LINK

1000

GOAL_CM_UINT32

4

Link status mask of interfaces

SPEED

1001

GOAL_CM_UINT32

4

Port speed mask of interfaces

DUPLEX

1002

GOAL_CM_UINT32

4

Port Duplex mask of interfaces

PORTCNT

1003

GOAL_CM_UINT32

4

Number of interfaces

Table 15 ETH Management interface

EIP


Module Id = GOAL_ID_EIP (23)

  • Internal variables used by the EtherNet/IP stack

HTTPD


Module Id = GOAL_ID_HTTP (25)

Variable Name

Variable ID

Type

Max. Size

Long description

HTTP_CHANNELS_MAX

0

GOAL_CM_UINT16

2

Determines the number of possible connections to the HTTP server

HTTPS_CHANNELS_MAX

1

GOAL_CM_UINT16

2

Determines the number of possible connections to the HTTPS server

USERLEVEL0

2

GOAL_CM_STRING

32

Authentication data for level 0

USERLEVEL1

3

GOAL_CM_STRING

32

Authentication data for level 1

USERLEVEL2

4

GOAL_CM_STRING

32

Authentication data for level 2

USERLEVEL3

5

GOAL_CM_STRING

32

Authentication data for level 3

Table 16 HTTP Management interface

CCM


Interface for Management Tool for informative and configuration purpose.
Module Id = GOAL_ID_CCM (72)

Variable Name

Variable ID

Type

Max. Size

Long description

SPI_TYPE

0

GOAL_CM_UINT8

1

SPI Type (currently only slave supported):0, SPI Master1, SPI Slave

SPI_MODE

1

GOAL_CM_UINT8

1

SPI Mode:0, CPOL=0; CPHA=01, CPOL=0; CPHA=12, CPOL=1; CPHA=03, CPOL=1; CPHA=1

SPI_SPEED

2

GOAL_CM_UINT8

1

SPI Speed in Master Mode

SPI_UNITWIDTH

3

GOAL_CM_UINT8

1

Bitsize of one single transfer unit:0, 8 Bit1, 16 Bit2, 32 Bit

SPI_BITORDER

4

GOAL_CM_UINT8

1

Bitorder of SPI transfers:0, MSB first1, LSB first

SPI_TRANSFERSIZE

5

GOAL_CM_UINT16

2

Minimum transfer size of single transmission frame

COMM_FAULT_ERROR_STATE

6

GOAL_CM_UINT8

1

Fault action to execute when communication to AC was lost during a cyclic connection:0, Enter fault state (disable connection)1, Keep running (keep connection)

COMM_SYNC_RESET

7

GOAL_CM_UINT8

1

Behaviour when a sync reset request was received from AC:0, Do nothing1, Perform reset of CC controller

FW_UPDATE_COMMIT_DISABLE

8

GOAL_CM_UINT8

1

Optional disable of the additional commit step during firmware update:0, Firmware update requires commit step1, Firmware update doesn't require a commit step

FOE_FILENAME

9

GOAL_CM_STRING

32

EtherCAT FoE update file name

FOE_PASSWORD

10

GOAL_CM_UINT32

4

EtherCAT FoE update password

FOE_UPDATE_REQUIRES_BOOT

11

GOAL_CM_UINT8

1

EtherCAT FoE update required state

FOE_FILENAME_MATCH_LEN

12

GOAL_CM_UINT8

1

EtherCAT FoE update file name match length

ETH_SWITCH_MODE_TIMEOUT

13

GOAL_CM_UINT8

1

General timeout for Ethernet interface activation

UPTIME

1000

GOAL_CM_UINT32

4

Number of seconds since start of device

Table 17 CCM Management interface

Firmware Update

Update the communication controller


Firmware update of the communiation controller is possible in the field. It is done using the Management tool. This tool uses the HTTP protocol to transfer a firmware package to the device.

Firmware package


Firmware image is bundled within a package. This package contains a signed firmware, which secures only acceptance of firmware from the device originator. Thus, it is possible for the device to check authenticity of the firmware image.

Control interface


By default, a firmware update is possible at any time. The communication module provides an interface to enable and disable the firmware update process. An application should use this interface as there are situations where a firmware update should not be accepted. This should be deactivated during an active cyclic connection to the PLC. For usage of this interface see chapter 6.1.

Optionally the application controller can register for events regarding firmware update. Then a start and finish of transfer is signalled to the application controller. Its task is also to trigger the reboot to the bootloader and performance of the actual firmware update. Beside that a failed or succeeded firmware update is reported to the application controller. The callback function can be registered using appl_ccmFwUpdateCbReg().

 

/****************************************************************************/ /** firmware update callback * */ static void appl_fwUpdateCb( FW_UPDATE_SOURCE_T source, /**< fw update source */ FW_UPDATE_STATUS_T state, /**< fw update status */ uint8_t progress /**< fw update progress */ ) { switch (state) { default: case FW_UPDATE_IDLE: goal_logInfo("fw update state : IDLE"); break; case FW_UPDATE_TRANSFER_INIT: goal_logInfo("fw update state : TRANSFER INIT"); switch (source) { case FW_UPDATE_SOURCE_RPC: goal_logInfo("fw update source : RPC"); break; case FW_UPDATE_SOURCE_HTTP: goal_logInfo("fw update source : HTTP"); break; case FW_UPDATE_SOURCE_FOE: goal_logInfo("fw update source : FOE"); break; } break; case FW_UPDATE_TRANSFER: goal_logInfo("fw update state : TRANSFER, progress = %d", progress); break; case FW_UPDATE_TRANSFER_DONE: goal_logInfo("fw update state : TRANSFER DONE"); goal_logInfo("performing update, rebooting CCM module"); /* perform actual update */ appl_ccmFwUpdateExecute(); break; case FW_UPDATE_ABORT: goal_logInfo("fw update state : ABORT"); break; case FW_UPDATE_COMMIT_PENDING: goal_logInfo("fw update state : PENDING"); break; case FW_UPDATE_COMMIT_DONE: goal_logInfo("fw update state : UPDATE DONE"); break; } }

Firmware update sequence

Firmware update is a two-step process. At first the firmware is uploaded to the http server of the CC module. Following checks are done during this check:

  1. This upload uses authentication with authentication level 0, where credentials are checked if configured for the HTTPD module. Those variables are configurable through the RPC interface of the HTTPD service. By default, these credentials are empty. Thus, any attempt to authenticate is accepted.

  2. The firmware update must be allowed by the AC. By default, this is the case. However, the AC can disable this function using the RPC interface.


If at the end of the transfer a valid firmware is detected, the module restarts and enters the bootloader. This software module checks the signature of the firmware and writes the correctly signed firmware to the memory of the device. As a fallback, the previously run firmware is kept. After restart of the module a successful communication to the management tool required to permanently enable the updated firmware. If this is possible, the module will restart again, and the bootloader will mark the new firmware as the current firmware. If this fails, the bootloader will revert to the original firmware with the next power cycle.

Keep update functionality while disabling DD


An application integrator might want to disable the DD feature to not expose any internal information of the device. Disabling is possible. However, to allow a firmware update using the management tool, the following steps need to be implemented:

1. Disabling DD by default


When calling the API function goal_ddNew, a bitmask can be passed, that determines the active DD features. If the predefined value GOAL_DD_FEAT_NO is used, DD is disabled completely.
Internally this value is stored to the CM variable FEATURE_DISABLE, which state also can be saved permanently to flash.

2. Introducing a switch to termporarily enable DD features


If a firmware update shall be processed, minimal DD features need to be set temporarily. These are:

  • HELLO REQUEST

  • SET CONFIG

  • GET CONFIG

  • SET IP


This can be done using the API function goal_ddSessionFeatureActivate() with the following arguments:


The temporary switch, to enable the management interface, can be implemented using the web server. See example 01_pnio_io_mirror for usage. As a result, the device will be invisible for the management tool. For firmware update, the required interface is temporarily activated, thus allowing to update the communication module firmware.

Update possibilities for application controller


By default, there is no firmware update available for the application controller. However, the module provides mechanisms for implementing such a feature within the customer application.
Following, two possible solutions are shown:

AC Firmware update over HTTP


The application controller can provide a web site or tool-based firmware update over HTTP transport, utilitung the provided RPC interface of the HTTPD service. As a starting point, the HTTPD example goal_http/02_post, respectively ccm example 20015013_irj45/01_pnio_io_mirror can be used.
For the latter, data for firmware update transported using a HTTP POST request will be processed in the callback function httpDataCbPost, for example as shown in the following sample code:

 

AC Firmware update over TCP


If HTTP is not favoured for transport of the firmware update, a plain TCP socket can be used for data transfer. This transport can be used the stream of data it provides, or any additional protocol can be used above this transport. See RPC interface of the networking tcp module.

Respectively, following callback function will handle received data: