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:

   uint8_t str[] = “myDev”; goal_ddCfgModuleName(str);

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:
   
   

   appl dout set <value> <mask>

    

2. Define the string variable in the source code:
   
   

   const char strAppl[] = “appl”; /* main-command */ const char strApplDout[] = “dout”; /* sub-command */ const char strApplSet[] = “set”; /* action */

    

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

   GOAL_STATUS_T applInitCli(void) { GOAL_STATUS_T res; /* GOAL return value */ GOAL_CLI_CMD_T *pApplCliHdl; /* handle to main-command */ GOAL_CLI_CMD_T *pApplCliSubHdl; /* handle to sub-commands */ /* register main-command */ res = goal_cliCmdReg(strAppl, NULL, applCmdHandler, NULL, pApplCliHdl); /* register sub-command */ if (GOAL_RES_OK(res)) { res = goal_cliCmdReg(strApplDout, NULL, NULL, pApplCliHdl, &pApplCliSubHdl); } /* register action */ if (GOAL_RES_OK(res)) { res = goal_cliCmdReg(strApplSet, NULL, NULL, pApplCliSubHdl, NULL); } return res; }

    

4. Implement the command handler applCmdHandler():
   
   

   void applCmdHandler( GOAL_CLI_DATA_T *pData /* [in] complete received command */ ) { GOAL_STATUS_T res; /* GOAL return value */ const char *pStr = NULL; /* string argument from the received command */ unsigned int len = 0; /* length of the argument in byte(s) */ uint8_t cmdFound = 0; /* flag to check the existence of the command */ /* The main-command is already analyzed by the GOAL command line interface and this command handler was called. */ /* eliminate sub-command from the received command */ res = goal_cliParamGet(pData, 1, &pStr, &len); if (GOAL_RES_OK(res)) { /* check sub-command */ if (strApplDout == pStr) { /* eliminate action */ res = goal_cliParamGet(pData, 2, &pStr, &len); if (GOAL_RES_OK(res)) { /* check support of action */ if (strApplSet == pStr) { /* execute application-specific action */ applDoutSet(); cmdFound = 1; } } } } /* print a response */ if ((GOAL_RES_OK(res)) && (1 == cmdFound)) { goal_cliPrintf(“command executed\n”); } else { goal_cliPrintf(“unknown command\n”); } return res; }

    

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.
   
   

   GOAL_STAGE_HANDLER_T stageApplCli; goal_mainStageReg(GOAL_STAGE_CLI, &stageApplCli, GOAL_STAGE_INIT, applInitCli);

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