Different kinds of GOAL extension modules can be divided:

• libraries for communication profiles provided by port GmbH

• more complex function blocks

Device Detection (DD)

The Device Detection represents a public interface to read and write CM-variables by other external components or remote devices. It is projected only for development and initial configuration purposes. During normal operation the Device Detection shall be disabled. The source code is located in the directory …\goal\protos\dd.
The Device Manager tool provides a graphical user interface to read and write CM-variables by a host computer using the Device Detection. This chapter describes a GOAL device used as counterpart to the Device Manager tool.
The Device Detection works according to the producer/consumer model, i.e. a DD-request of the DD-producer is received by one or more DD-consumers and each DD-consumer transmits a DD-response. Each DD-request must be answered by one or more DD-responses.

The data transfer between the DD-producer and DD-consumers is realized via a TCP/IP connection using the UDP protocol. All UDP datagrams are transmitted as broadcast packets to be independent on the IP configuration.

The data in the UDP datagram contains a DD-packet, which is coded according to the Device Detection protocol. The Device Detection protocol allows:

• to build groups of devices via a DD-customer-ID,

• to assign DD-requests and DD-responses to unique devices via the MAC address and

• to assign DD-requests to DD-responses.

Each DD-consumer can be assigned to a group by a DD-customer-ID. The DD-packet involves the DD-customer-ID of the group, which shall receive the DD-packet. The DD-customer-ID allows a filtering of the received DD-packets. The DD-customer-ID can be configured about the CM-variable DD_CM_VAR_CUSTOMERID. On the local device the CM-variable DD_CM_VAR_CUSTOMERID can be set by function goal_ddCfgCustomerID().

The DD-customer-ID 0 disables the filtering of the received DD-packets. A DD-consumer with the DD-customer-ID 0 accepts all DD-packets. A DD-packet with the DD-customer-ID 0 is received from all DD-consumers.

A symbolic name can be assigned to each device usable for graphical user interfaces. The remote device can set the symbolic name by the CM-Variable DD_CM_VAR_MODULENAME. On the local device the CM-variable DD_CM_VAR_MODULENAME can be set by function goal_ddCfgModuleName().

GOAL initializes the Device Detection automatically in the state GOAL_FSA_INIT if the Device Detection is enabled by the compiler-define GOAL_DD.

Configuration

Compiler-defines

The following compiler-defines are available to configure the Device Detection:

• GOAL_DD:

  • 0: Device Detection is disabled (default)

  • 1: Device Detection is enabled

CM-variables

The following CM-variables are available to configure the Device Detection:

Table: DD_CM_VAR_MODULENAME

Table: DD_CM_VAR_CUSTOMERID

Implementation guide

Initial disabling of features by the application

With the call of goal_ddNew() from appl_setup() a bitmask can be passed with 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.

The described mechanism can also be set before application start by setting the corrensponding CM variable FEATURE_DISABLE. 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.

• 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:

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:

Configure the local device

The local device shall support the Device Detection, therewith the Device Manager tool can set and get CM-variables.

1. GOAL initializes the Device Detection automatically in the state GOAL_FSA_INIT if the Device Detection is enabled by the compiler-define GOAL_DD.

2. Set the DD-customer-ID to 1:
   
   

   goal_ddCfgCustomerID(1);

    

3. Set the device name:

4. Now the Device Manager tool can read and write CM-variables on the device “myDev”.

Command line interface (CLI)

GOAL provides a command line interface, which is used by GOAL core modules and other GOAL extension modules. The available commands for the command line interface are described in the appropriate chapters. But it is also possible to integrate a command line interface for the own application, see Chapter: Command structure. The source code of the GOAL command line interface is located in the directory …\goal\protos\cli.
The command line interface supports the auto-completion of commands and provides a command history. The size of the command history is configurable during compilation.
The data exchange about the command line interface is realized

• via a UART connection

For further medias please contact port.
The command line interface provides an interface for debugging, see Chapter: Command line interface for debugging.

• example:

  • …\goal\appl\00410_goal\cli*

Configuration

The following compiler-defines are available to configure the command line interface:

• GOAL_CONFIG_CLI:

  • 0: command line interface is disabled (default)

  • 1: command line interface is enabled

• GOAL_CONFIG_CLI_HISTORY:

  • 0: history of the command line interface is disabled (default)

  • 1: history of the command line interface is enabled

• GOAL_CONFIG_CLI_HISTORY_SIZE:

  • number of history entries

• GOAL_CONFIG_CLI_UART:

  • 0: command line interface is not connected via UART (default)

  • 1: command line interface is connected via UART

• GOAL_CONFIG_CLI_DBG:

  • 0: debug interface of the command line interface is disabled (default)

  • 1: debug interface of the command line interface is enabled

Platform API

UART connection

Table: goal_tgtCharGet()

Table: goal_tgtCharPut()

Command structure

Each CLI command is composed of:

• a main-command,

• one or more sub-commands,

• an action and

• one or more optional parameters.

Main-command

port recommends to use "appl" as main-command for application-specific commands to separate these commands from the existing commands in the GOAL system.

Sub-command

The sub-command is any specific name.

Action

Table 12 provides an overview about binding action names for standard actions. Not all actions must be implemented by a specific command.

Table: command line standard action

Parameters

Integer values

Integer values are currently only accepted with a base of 10 and may optionally contain a sign.
Example: The following command sets the port membership of port 1 to VLAN 1024:

Strings

Strings are started and ended with a "-character.
Example: The following command sets the value of config variable 0-1 to value "example"

Port numbers

Ports are entered as integer values starting with 0 up to max. port number + 1. Max. port number +1 represents the management port. A 5 port switch provides ports 0 – 3 (external ports) and port 4 as management port.
Example: The following commands set the default VLAN tag for port 1 to 1024 with prio 7:

MAC addresses

MAC addresses are given in the format xx:xx:xx:xx:xx:xx where xx stands for a two char hex number.
Example: The following command adds port 3 to MAC address 00:11:22:33:44:55

IP addresses

IP addresses are given in the format xxx.xxx.xxx.xxx where xxx stands for a one- to three-digit decimal number.
Example: The following command sets the IP address, netmask and gateway for the TCP/IP stack:

Creating application-specific commands

The following steps are necessary to implement application-specific commands for the command line interface:

1. Create commands, see Chapter: Command structure.

2. Implement the initialization of the application-specific command line interface.

3. Implement command handlers for main- and sub-commands.

4. Register commands to the command line interface by function goal_cliCmdReg() and make the command handlers of the own commands known.

5. The commands are processed loop-controlled in the state GOAL_FSA_OPERATION. It is possible to return a response by function goal_cliPrintf().

Chapter 7.2.6.1 shows an example.

Command line interface for debugging

The following commands are available for the debug interface:

Table: dbg memb show

Table: dbg memw show

Table: dbg memd show

Implementation guidelines

Create application-specific commands

This example assumes that the command line interface is implemented in an own C module, e.g. appl_cli.c.

1. Digital outputs shall be set via the command line interface. The given value is bit-coded. Each bit relates to a specific DOUT channel. The relevance of the bits in the value can be managed by a bit mask. According to chapter 7.2.3 the command name is:
   
   

    

2. Define the string variable in the source code:
   
   

    

3. Implement the initialization function to register the commands and to make the handler applCmdHandler() for all commands known:
   
   

    

4. Implement the command handler applCmdHandler():
   
   

    

5. Implement the application-specific function applDoutSet() to handle the DOUTs.

6. Register the initialization of the application-specific command line interface. The initialization shall be executed in stage GOAL_STAGE_CLI in state GOAL_FSA_INIT_GOAL.
   
   

Web-server

GOAL provides a smart web-server for embedded systems. The web-server was designed:

• for file downloads and

• to get information about the current device state and properties.

The web-server supports the following properties:

One or more web-pages can be assigned to one instance of the web-server. The web-pages are part of the application and must be made available by the application. The web-server provides a callback function for this purpose, see cbHttpReqFunc() in Chapter: Callback functions.
The current device state and properties can be read from CM-variables and application-specific variables. The application-specific variables can be organized as simple variables or as a one-dimensional list.
It is possible to store templates for web-pages with placeholders for current values of application-specific variables. The text substitutions are described in Chapter: Web-templates. Web-templates make the dynamic management of web-pages possible.
The access to the web-server can be limited by user levels. The application can specify, which user levels shall be supported by the device and which rights the user levels shall have. The authentication data consisting of user name and the password for each user level are configurable by CM-variables. The GOAL web-server provides up to 4 user levels.
The user levels can be applied by all instances of the web-server. For each instance of the web-server the valid user level can be specified during registration. Web-requests are only transferred to the application after a successful authentication, i.e. the callback function cbHttpReqFunc() in Chapter: Callback functions. is only called after a successful login. The transfer of the user name and the password via a web-server instance using the HTTP transfer protocol is unsafe. port recommends using the HTTPS transfer protocol.
HTTPS is activated by the compiler-define GOAL_CONFIG_HTTPS. HTTPS uses the TLS media interface for encoding and authentication. This allows to use different TLS software, like Mbed TLS and WolfSSL, see Chapter: TLS. TLS for HTTPS is initialized and opened by function goal_httpsNew().
About the CM-variables for HTTPS it is possible to install a private key and an own X509-certificate for. If no own certificate is stored, the web-server takes a default certificate provided by port.

example:

• …\goal\appl\goal_http\01_get*:

  • for upload of a web-page

• …\goal\appl\goal_http\05_template_cm*:

  • for upload of a web-template with CM-variables and application-specific variables

• …\goal\appl\goal_http\06_template_list*:

  • for upload of a web-template with lists

• …\goal\appl\goal_http\04_auth*:

  • for authentication about user levels

• …\goal\appl\goal_http\02_post*:

  • for file download

Configuration

Compiler-defines

The following compiler-defines are available to configure the webserver:

• GOAL_CONFIG_HTTP:

  • 0: transfer protocol HTTP is not used (default)

  • 1: transfer protocol HTTP is used

• GOAL_CONFIG_HTTPS:

  • 0: transfer protocol HTTPS is not used (default)

  • 1: transfer protocol HTTPS is used

CM-variables

The following CM-variables are available to configure the web-server:

Table: HTTPD_CM_VAR_HTTPD_CHANNELS_MAX

Table: HTTPD_CM_VAR_HTTPS_CHANNELS_MAX

Table: HTTPD_CM_VAR_USERLEVEL0

Table: HTTPD_CM_VAR_USERLEVEL1

Table: HTTPD_CM_VAR_USERLEVEL2

Table: HTTPD_CM_VAR_USERLEVEL3

The following CM-variables allow to configure the TLS layer used by HTTPS:

Table: HTTPS_CM_VAR_TLS_SERVER_CERTIFICATE

Table: HTTPS_CM_VAR_TLS_PRIVATE_KEY

Table: HTTPS_CM_VAR_TLS_SRV_CERT_CA_CN

Table: HTTPS_CM_VAR_TLS_SRV_CERT_CA_O

Table: HTTPS_CM_VAR_TLS_SRV_CERT_CA_C

Table: HTTPS_CM_VAR_TLS_SRV_CERT_CN

Table: HTTPS_CM_VAR_TLS_SRV_CERT_O

Table: HTTPS_CM_VAR_TLS_SRV_CERT_C

Table: HTTPS_CM_VAR_TLS_SRV_CERT_NOT_BEFORE

Table: HTTPS_CM_VAR_TLS_SRV_CERT_NOT_AFTER

Web-templates

The GOAL web-server allows to implement templates for web-pages with placeholders for current information. The placeholders are substituted by the current values by the web-server during the upload process. The web-server provides placeholders for

• CM-variables,

• application-specific variables and

• lists.

CM-variables

The placeholder for CM-variables contains the CM-module-ID and the CM-variable-ID. The web-server executes the substitution of the placeholder by the CM-variable automatically.

• syntax:

  • [CM:<modNum>, <cmVarNum>]

• example:

  • [CM:0, 2]

Application-specific variables

The placeholder for application-specific variables contains the name of the variable in the application. The web-server requires the current value of the variable from the application by calling a callback function, see Chapter: Callback functions cbHttpTemplateFunc(), and substitutes the placeholder in the web-page.

• syntax:

  • [VAR:<applVarName>]

• example:

  • [VAR:applVar]

Lists

The web-server provides an effective method to generate lists in HTML text. The HTML text for a single list entry can be enclosed in the placeholders FOREACH and /FOREACH in the web-template. FOREACH marks a one-dimensional list and the HTML text between the placeholders FOREACH and /FOREACH is execute for each list element. The place for the list entry is marked in the HTML text by the placeholder VAR with the desired variable name. After the substitution of the placeholder VAR the web-server changes to the next list entry automatically, i.e. it is not possible to substitute the same list entry twice. Therewith it is only necessary to describe the first list entry in the web-template.
The web-server only gets the ID and the name of the list and the number of list elements during the registration. The content of the list elements is managed by the application. The web-server calls a callback function to get the content of the next list element, see Chapter: Callback functions cpHttpTemplateFunc().
Nested lists are allowed. The maximal supported nesting depth is 4.

• syntax:

  • [FOREACH:<listName>] … [/FOREACH]

• example for HTML listing:
  
  

The placeholder [FOREACH] … [\FOREACH] can also be integrated in other HTML formatting like tables.

Characters

square brackets: If the HTML text shall show square brackets, the square brackets must be written double, because placeholders in web-templates are bordered by square brackets.
example:

• An array instruction shall be shown on a web-page.

  • HTML text: applArray[[5]]

  • Web-browser view: applArray[5]
    
    

double quotes: Double quotes in the HTML-text must be protected by a backslash, because strings in the C code are enclosed by double quotes.
example:

The rules for HTML text are valid for all other characters.

Callback functions

Table: cbHttpReqFunc()

Table: cbHttpReqFunc()

Implementation guideline

Upload a web-page

The web-page "device.html" shall be uploaded from the device to the web-browser. The content of the web-page is stored in variable webPage[] as string. No text substitutions on the web-page are necessary.

1. Initialize the web-server in state GOAL_FSA_INIT_APPL or GOAL_FSA_INIT_GOAL:
   
   

    

2. Open 1 instance of the web-server using the TCP port 8080 in state GOAL_FSA_INIT_SETUP:
   
   

    

3. Register the callback-functions and allowed methods for the opened web-server in state GOAL_FSA_INIT_SETUP: No callback function for text substitution is registered.
   
   

    

4. Provide the web-page as string variable:
   
   

    

5. Implement a callback function to process web-requests:
   
   

    

6. The callback function applWebReqCb() is called by the web-server after the receipt of the web-request.

Read a CM-variable

The web-page "device.html" shall be uploaded from the device to the web-browser. The web-page bases on the template webPage[]. The template includes a placeholder for the CM-Variable DD_CM_VAR_MODULENAME with the CM-module-ID 34 and the CM-variable-ID 0. The web-server substitutes the placeholder by the current value of the CM-variable automatically. No text substitutions on the web-page are necessary.

1. Initialize the web-server in state GOAL_FSA_INIT_APPL or GOAL_FSA_INIT_GOAL:
   
   

    

2. Open 1 instance of the web-server using the TCP port 8080 in state GOAL_FSA_INIT_SETUP:
   
   

    

3. Register the callback-functions and allowed methods for the opened web-server in state GOAL_FSA_INIT_SETUP: No callback function for text substitution is registered.
   
   

    

4. Provide a template for the web-page as string variable with placeholder for the CM-variable:
   
   

    

5. Implement a callback function to process web-requests:
   
   

    

6. The callback function applWebReqCb() is called by the web-server after the receipt of the web-request.

Read application-specific variable

The web-page "device.html" shall be uploaded from the device to the web-browser. The web-page bases on the template webPage[]. The template includes a placeholder for the application-specific Variable applVar. The web-server calls the callback function applWebGetValCb() to provide the current value of the application-specific variable for the web-server. The web-server substitutes the placeholder by the current value of the application-specific variable.

1. Initialize the web-server in state GOAL_FSA_INIT_APPL or GOAL_FSA_INIT_GOAL:
   
   

    

2. Open 1 instance of the web-server using the TCP port 8080 in state GOAL_FSA_INIT_SETUP:
   
   

    

3. Register the callback-functions and allowed methods for the opened web-server in state GOAL_FSA_INIT_SETUP:
   
   

    

4. Provide a template for the web-page as string variable with placeholder for the application-specific variable:
   
   

    

5. Implement a callback function to process web-requests:
   
   

    

6. Implement a callback function to get the current value of the application-specific variable from the application:
   
   

    

7. The callback function applWebReqCb() is called by the web-server after the receipt of the web-request. The desired template for the web-page is made available for the web-server.

8. The callback function applWebGetValCb() is called for substitution.

Read a list

The web-page "device.html" shall be uploaded from the device to the web-browser. The web-page bases on the template webPage[]. The template includes a placeholder for the list of device components. The web-server calls the callback function applWebGetValCb() to provide the current value of the list entries. The web-server substitutes the placeholder by the current value of the application-specific variable.

1. Initialize the web-server in state GOAL_FSA_INIT_APPL or GOAL_FSA_INIT_GOAL:
   
   

    

2. Open 1 instance of the web-server using the TCP port 8080 in state GOAL_FSA_INIT_SETUP:
   
   

    

3. Register the callback-functions and allowed methods for the opened web-server in state GOAL_FSA_INIT_SETUP:
   
   

    

4. Create the list information and register the list information for the web-server. The list information contains a list-ID, a list name and the number of list entries.
   
   

    

5. Provide a template for the web-page as string variable with placeholders for the list and list entries:
   
   

    

6. Implement a callback function to process web-requests:
   
   

    

7. Implement a callback function to get the current value of the list entries from the application:
   
   

    

8. The callback function applWebReqCb() is called by the web-server after the receipt of the web-request. The desired template for the web-page is made available for the web-server.

9. The callback function applWebGetValCb() is called for each substitution.

Set a user level

The upload of the web-page "admin.html" shall only allowed for users with the USERLEVEL0. The login data for the USERLEVEL0 are:

• user name: admin

• password: a1b2c3:UL

The HTTPS transfer protocol is used.
The web-page "admin.html" does not contain any placeholder. No text substitutions on the web-page are necessary.

1. Initialize the web-server in state GOAL_FSA_INIT_APPL or GOAL_FSA_INIT_GOAL:
   
   

    

2. Open 1 instance of the web-server using the TCP port 443 in state GOAL_FSA_INIT_SETUP:
   
   

    

3. Register the callback-functions and allowed methods for the opened web-server in state GOAL_FSA_INIT_SETUP:
   
   

    

4. Install the authentication for USERLEVEL0 in state GOAL_FSA_INIT_SETUP: The authentication data are written to the CM-variable USERLEVEL0.
   
   

    

5. Provide a template for the web-page as string variable:
   
   

    

6. Implement a callback function to process web-requests:
   
   

    

7. The callback function applWebReqCb() is called by the web-server after the receipt web-request. The login for this web-server instance must be successful before.

Download files

The web-server provides a download dialog. The received file is transferred to the application.

1. Initialize the web-server in state GOAL_FSA_INIT_APPL or GOAL_FSA_INIT_GOAL:
   
   

    

2. Open 1 instance of the web-server using the TCP port 8080 in state GOAL_FSA_INIT_SETUP:
   
   

    

3. Register the callback-functions and allowed methods for the opened web-server in state GOAL_FSA_INIT_SETUP:
   
   

    

4. Provide a web-page as string variable:
   
   

    

5. Implement an application-specific function applDownload() to receive and install the new firmware.

6. Implement an application-specific function applDownloadFinished() to report the result of the web-request to the application.

7. Implement a callback function to process web-requests:
   
   

Application Programming Interface

Initialization

goal_httpNewImpl()

Registers the http module for GOAL.

Return values:

GOAL_STATUS_T result

Parameters:

• ppInst pointer to instance pointer

• port port to link instance to

• cntChn channel count

goal_httpResReg()

Parameters:

• pInst instance pointer

• strUrl URL string

• allowMeth allowed methods for resource

• pfnCbData application callback

• pfnCbTemplate template handler callback

• pHdl resource handle return

Firewall

GOAL provides a basic firewall for ARP, TCP and UDP. After calling goal_fwInit() the firewall is active and working. All frames received in goal_miEthRecv() matching ether type ARP and IPv4 will be passed to and processed by the firewall.

ARP-Firewall

All received Ethernet frames of ether type ARP will be filtered by goal_fwArp(). The firewall will process frames that match the following conditions:

• EtherType = 0x0806 (Address Resolution Protocol)​

• Data length must be equal or higher than 96 bytes​

• ARP hardware type is Ethernet - 0x0001​

• Opcode is request – 0x01​

• Protocol type is IPv4 – 0x0800​

Frames that doesn't match these conditions will be passed to the queue. The ARP-firewall drops all frames that are not addressed to the device or have MAC-Address NULL. The firewall reads the IP, Gateway and Netmask settings at initialization and gets updated automatically at any change of these values.

IPv4-Firewall

All received Ethernet frames of ether type IPv4 will be filtered by goal_fwIpv4(). All frames of type ICMP will be passed directly to the queue. For TCP and UDP the firewall:

• Checks frame length and drops malformed frames

• Iterates through all channels to check for matching port number on used channels

• Drops frames with no matching port number

The firewall reads the maximum number of net-channels and the location of the cannel list at initialization.