How to understand the structure of Hilschers host application examples?

Overview

Hilscher offers a number of example applications, published in the Knowledge Base →  LFW Host Examples

The examples are implemented in ANSI C.

Each example represents the implementation of a network (slave) device which produces and consumes IO-data. All examples are very similar and represent the same device from the application point of view.

In order to support and demonstrate different protocols and different host architectures, the example applications are structured in a modular way.

The projects are separated into 3 parts

1. Application - YELLOW
2. Protocol specific parts - GREEN
3. Hardware specific parts - RED

Each part is modular and independent of any other part. E.g.the same application source code can be combined with any protocol specifc code and with any hardware specific code.

In the table above, 4 differnet example applications are listed. All applications use the same application source code (Application Module 1) and the same hardware specific source code (netX 90 APP). Only the protocol specific parts are different in each example.

In order to support an additional host architecture, like STM32 MCUs or a Windows PC, only the RED component must be replaced.

Once you are familiar with the project structure of one single example, it is easy to migrate to a different protocol or to a different hardware platform, since most software components are the same.

Block Diagram

Mapping to Project Components

Application Part - YELLOW

The application part, more concrete the function App_DemoApplication(), is the entry point of the example application. The function App_DemoApplication() is called in main.c

The application part is based on the cifX API (by using the cifX Toolkit or a driver from Hilscher, like the cifX Windows or Linux Driver) and a simple hardware abstraction layer, thus independent of any hardware. I.e. the same application parts can be used with any hardware platform like netX 90 APP, STM32 MCU, Windows PC, Linux, etc..

The effort for migration to a custom hardware platform, not supported by Hilscher yet, is not high. Only the RED parts of the example must be adapted to the specific host hardware.

Furthermore it contains only generic application parts without any protocol specific code. I.e. the same application parts can be used for any protocol example like PROFINET, EtherCAT, EthernetIP, PROFIBUS, etc.

The application example projects, provided by Hilscher, do not use an operating system. Though it is feasible to port the application example to a system including an RTOS using several OS tasks.

The YELLOW application part is splitted into several C-modules for clarity. These are represented by grey boxes in the block diagram above. In the published projects, the YELLOW application part and all its C-Modules are composited in the component "cifXApplicaionDemo".

The component provides basic, generic mailbox packet service routines to send and receive mailbox packets.

The body of the application has two main parts: 1) The main loop (while 1 loop) for "slow" less prior tasks like DPM mailbox packet handling, and 2) a cyclic timer interrupt service routine for "fast", higher prior IO data handling → App_IODataHandler() function.

Before entering the main loop and cyclic handling of the timer ISR, several configuration steps are executed: Opening the DPM channels (xChannelOpen()), retrieving information about the LFW on the netX communication side (xChannelInfo()) and configuration of the protocol stack (Protocol_StartConfiguration()).

The modeled IO device features 2 sensors (producing output data) and 2 actuators (consuming input data). Beside the actual sensor/actuator data, the IO data image contains state and mode information as well as a counter. The example applications do not fully implement the device functionality. I.e. the actual sensor/actuator data is not important and usually just dummy data. Depending on the available resources of the hardware platform, the data (or parts of it) might be output to LEDs, inputs might be DIP-switches or the netX 90 build in tempertaure sensor, etc. The data is provided/consumed by the hardware abstarction layer functions (HOSTAL - host abstraction layer)

List of C-files

Generic Application (cifX API based)

IO-Data

Protocol Part - GREEN

The protocol part is based on the cifX API (by using the cifX Toolkit or a driver from Hilscher, like the cifX Windows or Linux Driver) and a simple hardware abstraction layer, thus independent of any hardware. I.e. the same protocol component can be used with any hardware platform like netX 90 APP, STM32 MCU, Windows PC, Linux, etc..

The effort for migration to a custom hardware platform, not supported by Hilscher yet, is not high. Only the RED parts of the example must be adapted to the specific host hardware.

In contrast to the generic YELLOW application part, the GREEN protocol part is specifc for the different Hilscher Protocol LFWs like PROFINET, EtherCAT, ...

The GREEN protocol part is splitted into several C-modules for clarity. These are represented by grey boxes in the block diagram above. In the published projects, the GREEN protocol part and all its C-Modules are composited in the component "cifXApplicaionDemoXXX", where XXX is replaced by the respective protocol abbreviation (PNS - PROFINET slave, EIS, EthernetIP slave, ECS - EtherCAT slave, etc.).

The component provides 3 main functions, which are called from the YELLOW application part:

1. Protocol_StartConfiguration()
2. Protocol_PacketHandler() and subsequently AppXXX_Protocol_PacketHandler()
3. Protocol_EventHandler()

1) is called only once during the initialization phase, 2) is called cyclically from the main loop in order to check and handle incoming mailbox packets. 3) may be used to demonstrate the implementation of protocol specific asyclic communication, like diagnosis or alarms, etc.. 3) is not implemented and just an empty function in most examples

Hilscher LFWs might feature several DPM communication channels with different functionality (refer to article Firmware Variants). Each channel might be handled by an independent GREEN protocol component. Mostexamples demonstrate the usage of just one DPM communication channel.

List of C-files

Protocol dependent part of the application (cifX API based)

^{XXX= PNS, EIS, ECS, PLS, etc.}

Hardware Dependent Part - RED

The hardware dependent parts might differ significantly between each host hardware platform. An embedded Cortex-M based host controller must be setup differently than a Linux or Windows based PC Host device.

The RED part provide 3 main functiionalities

1. initialize the system/application and entry point main()
2. cifX API as base for the application
3. HOSTAL - hardware abstraction layer

During execution of 1, startup code (typically assembler code in embedded systems) for interrupt setup etc. is executed, the cifX Driver or cifX Toolkit is initialized, communication interfaces (like UART or SPI) are initialized and the application demo is started by call of function  App_DemoApplication().

2), the cifX API is base for the YELLOW application part and GREEN protocol part. In embedded systems typically the cifX Toolkit component is implemented. On Windows or Linux hosts, a Hilscher driver (e.g. DLL), ready to use, can be utilized.
Note: The example projects, provided by Hilscher, do not contain full cifXToolkit adaptions (adaption of OS_Custom.c) which meet requirements for all use cases. It is always necessary and in the responsibility of the user, to adapt and test the cifXToolkit customization, according to the requirements. Particularly when an RTOS is used, the cifX Toolkit must be adapted respectively. Also usage of interrupt mode requires adaption to cifXToolkit customization functions.

3) The host hardware abstraction layer mainly provides functions for data consumption and production, depending on the available hardware. In general the actual generated data is not relevant, dummy data is sufficient. Furthermore the HOSTAL is responsible to provide a service for cyclic function calls (e.g. by using a timer interrupt) for call of App_IODataHandler()

List of C-files

Hardware (target) dependent components of the application

Overview HOSTAL functions: