{"type":"doc","content":[{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{"minLevel":{"value":"1"},"maxLevel":{"value":"2"},"outline":{"value":"false"},"style":{"value":"default"},"type":{"value":"list"},"printable":{"value":"true"}},"macroMetadata":{"macroId":{"value":"019309a2-95af-4500-990d-fc74fd19b01b"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"f8389230-fa77-4968-9f0c-61ca1992a181"}},{"type":"heading","attrs":{"level":1},"content":[{"text":"Introduction","type":"text"}]},{"type":"paragraph","content":[{"text":"This document provides information about how to build an application for the irj45 communication module.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Basic application setup","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"},{"text":"A basic application consists of the optional function calls ","type":"text"},{"text":"appl_init","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"appl_setup","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"appl_loop","type":"text","marks":[{"type":"code"}]},{"text":". It follows the design philosphy of the GOAL middleware.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Default Features","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Web Server with Device Detection","type":"text"}]},{"type":"paragraph","content":[{"text":"By default, the System-on-Module starts a web server (on port 8080) for the firmware update feature and an instance of ","type":"text"},{"text":"Device Detection","type":"text","marks":[{"type":"link","attrs":{"href":"https://portgmbh.atlassian.net/wiki/spaces/ICE/pages/7307304"}}]},{"text":" for management using the ","type":"text"},{"text":"Industrial Communication Explorer","type":"text","marks":[{"type":"link","attrs":{"href":"https://portgmbh.atlassian.net/wiki/spaces/ICE"}}]},{"text":". It is not possible by the application controller to disable the web server on the System-on-Module. However, the application controller can start another instance of the web server.","type":"text"}]},{"type":"paragraph","content":[{"text":"The activaed Device Detection allows full access to all variables and logs on the module. Device Detection bases on a simple UDP based protocol with no encryption. Thus, an application can and ","type":"text"},{"text":"should","type":"text","marks":[{"type":"em"}]},{"text":" limit the access to a feasable range. Limitation of features and access is possible on various levels.","type":"text"}]},{"type":"paragraph","content":[{"text":"The access can be fully modified using the appropriate ","type":"text"},{"text":"API described at the DD documentation","type":"text","marks":[{"type":"link","attrs":{"href":"https://portgmbh.atlassian.net/wiki/spaces/GOALR/pages/edit-v2/191562330#Implementation-guide"}}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Profinet","type":"text"}]},{"type":"paragraph","content":[{"text":"The communication module contains a full featured Profinet slave stack. For application see the proper ","type":"text"},{"text":"PROFINET documentation","type":"text","marks":[{"type":"link","attrs":{"href":"https://portgmbh.atlassian.net/wiki/spaces/PNIO/pages/354058270"}}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"EtherNet/IP","type":"text"}]},{"type":"paragraph","content":[{"text":"The communication module contains a full featured EtherNet/IP slave stack. For application see the proper ","type":"text"},{"text":"EtherNet/IP documentation","type":"text","marks":[{"type":"link","attrs":{"href":"https://portgmbh.atlassian.net/wiki/spaces/ETIP/pages/227999768"}}]},{"text":". ","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"EtherCAT","type":"text"}]},{"type":"paragraph","content":[{"text":"The communication module contains a full featured EtherCAT slave stack. For application see the ","type":"text"},{"text":"EtherCAT stack documentation","type":"text","marks":[{"type":"link","attrs":{"href":"https://portgmbh.atlassian.net/wiki/spaces/ECAT/pages/202145915/EtherCAT+-+User+Manual?atlOrigin=eyJpIjoiYWZiYjFkZGZkNjc1NDFjMDljYjI1ODc0NWUyZmY2MDYiLCJwIjoiYyJ9"}}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"HTTPD","type":"text"}]},{"type":"paragraph","content":[{"text":"The communication module contains a web server for basic management functionality. Please refer to the proper ","type":"text"},{"text":"HTTPD documentation","type":"text","marks":[{"type":"link","attrs":{"href":"https://portgmbh.atlassian.net/wiki/spaces/GOALR/pages/191562330/GOAL+extension+modules+protos#Web-server"}}]},{"text":" as part of the GOAL - Programmer’s Manual.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Network channels","type":"text"}]},{"type":"paragraph","content":[{"text":"The communication module provides TCP and UDP communication channels. Please refer to the API documentation within this document for detailed description.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Generic Data Provider","type":"text"}]},{"type":"paragraph","content":[{"text":"For fieldbus communication applications a generic data provider is available, which contains gneralized information and led status for the application. ","type":"text"}]},{"type":"table","attrs":{"layout":"wide","width":960.0,"localId":"205de684-320f-4882-bc5f-ad5e5148f7cf"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[331.0]},"content":[{"type":"paragraph","content":[{"text":"Data Provider Information","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[157.0]},"content":[{"type":"paragraph","content":[{"text":"PROFINET","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[186.0]},"content":[{"type":"paragraph","content":[{"text":"EtherNet/IP","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"EtherCAT","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[331.0]},"content":[{"type":"paragraph","content":[{"text":"GOAL_MCTC_DP_STATUS_FLG_CONN","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[157.0]},"content":[{"type":"paragraph","content":[{"text":"Connection","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[186.0]},"content":[{"type":"paragraph","content":[{"text":"Connection","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"Connection (ESM-State == OP)","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[331.0]},"content":[{"type":"paragraph","content":[{"text":"GOAL_MCTC_DP_STATUS_FLG_ERR","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[157.0]},"content":[{"type":"paragraph","content":[{"text":"Error","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[186.0]},"content":[{"type":"paragraph","content":[{"text":"Error","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"Application Layer Error","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[331.0]},"content":[{"type":"paragraph","content":[{"text":"GOAL_MCTC_DP_STATUS_FLG_VALID","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[157.0]},"content":[{"type":"paragraph","content":[{"text":"-","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[186.0]},"content":[{"type":"paragraph","content":[{"text":"Process data valid","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"Process data valid","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[331.0]},"content":[{"type":"paragraph","content":[{"type":"hardBreak"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[157.0]},"content":[{"type":"paragraph","content":[{"type":"hardBreak"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[186.0]},"content":[{"type":"paragraph","content":[{"type":"hardBreak"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"type":"hardBreak"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[331.0]},"content":[{"type":"paragraph","content":[{"text":"GOAL_MCTC_DP_LED_WINK","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[157.0]},"content":[{"type":"paragraph","content":[{"text":"DCP blink signaling","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[186.0]},"content":[{"type":"paragraph","content":[{"text":"-","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"-","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[331.0]},"content":[{"type":"paragraph","content":[{"text":"GOAL_MCTC_DP_LED_RED1","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[157.0]},"content":[{"type":"paragraph","content":[{"text":"Error","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[186.0]},"content":[{"type":"paragraph","content":[{"text":"Module Status red","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"EC ERR Led May be configured to a STATUS Indicator, wher only LED_GREEN1 and LED_RED_1 are used.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[331.0]},"content":[{"type":"paragraph","content":[{"text":"GOAL_MCTC_DP_LED_RED2","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[157.0]},"content":[{"type":"paragraph","content":[{"text":"Maintainance","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[186.0]},"content":[{"type":"paragraph","content":[{"text":"Network Status red","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"(optional: part of the STATUS indicator)","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[331.0]},"content":[{"type":"paragraph","content":[{"text":"GOAL_MCTC_DP_LED_GREEN1","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[157.0]},"content":[{"type":"paragraph","content":[{"text":"Connection","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[186.0]},"content":[{"type":"paragraph","content":[{"text":"Module Status green","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"EC RUN Led","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[331.0]},"content":[{"type":"paragraph","content":[{"text":"GOAL_MCTC_DP_LED_GREEN2","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[157.0]},"content":[{"type":"paragraph","content":[{"text":"DCP blink signaling","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[186.0]},"content":[{"type":"paragraph","content":[{"text":"Network Status green","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"-","type":"text"}]}]}]}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"The LED status information are a recommendation regarding conformance/usability of a device implementation. The delivered examples show usage of this feature. ","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Ethernet Startup Delay","type":"text"}]},{"type":"paragraph","content":[{"text":"With integration of EtherCAT in version 2.0.0.0 of the 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. ","type":"text"}]},{"type":"paragraph","content":[{"text":"A System-on-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: ","type":"text"}]},{"type":"table","attrs":{"layout":"default","width":760.0,"localId":"c6d5464d-4d8f-481f-94b0-e0bbbe6b7a72"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[228.0]},"content":[{"type":"paragraph","content":[{"text":"Timeout value","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[532.0]},"content":[{"type":"paragraph","content":[{"text":"function","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[228.0]},"content":[{"type":"paragraph","content":[{"text":"0","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[532.0]},"content":[{"type":"paragraph","content":[{"text":"default timeout enabled (5 seconds)","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[228.0]},"content":[{"type":"paragraph","content":[{"text":"1 ... 254","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[532.0]},"content":[{"type":"paragraph","content":[{"text":"value determines timeout in seconds","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[228.0]},"content":[{"type":"paragraph","content":[{"text":"255","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[532.0]},"content":[{"type":"paragraph","content":[{"text":"timeout disabled","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"External Reset","type":"text"}]},{"type":"paragraph","content":[{"text":"The module provides an external reset input, where the AC can perform a reset of the module. ","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"Do not perform this reset during a firmware update of the CC. This will prevent proper update functionality. ","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Therefore, it is recommended to utilize this reset only if the AC module is initially powered up (cold start).","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"RPC Synchronization reset","type":"text"}]},{"type":"paragraph","content":[{"text":"If either AC or CC restart, the peer module is required to restart too. Else a repeatedly RPC synchronization is not possible.","type":"text"}]},{"type":"paragraph","content":[{"text":"By default, the System-on-Module does not perform a reset implicitly. If the AC application restarts, a power cycle of the module (or a manual reset) is required. It is possible to configure this behaviour using the CM variable interface.","type":"text"}]},{"type":"paragraph","content":[{"text":"The AC performs a reset of it's application on request of the System-on-Module, e.g. when the module restarts. This can happen during a firmware update.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"IP Settings","type":"text"}]},{"type":"paragraph","content":[{"text":"IP Settings can be done with the Industrial Communication Explorer, via ","type":"text"},{"text":"goal_maNetIpSet()","type":"text","marks":[{"type":"code"}]},{"text":" or CM access, as described following:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Set CM Variable GOAL_ID_NET:IP to configure IP address,","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Set CM Variable GOAL_ID_NET:NETMASK,","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Set CM Variable GOAL_ID_NET:GW,","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Set CM Variable GOAL_ID_NET:Valid to 1,","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Set CM Variable GOAL_ID_NET:DHCP_ENABLED to 0,","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Set CM Variable GOAL_ID_NET:COMMIT to 1","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"To enable DHCP set the CM Variable GOAL_ID_NET:DHCP_ENABLED to 1 and perform a power cycle.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Management Interface CC","type":"text"}]},{"type":"paragraph","content":[{"text":"See the ","type":"text"},{"text":"Configuration Manager","type":"text","marks":[{"type":"link","attrs":{"href":"https://portgmbh.atlassian.net/wiki/spaces/GOALR/pages/236585089/Configuration+Manager+goal_cm#Variable-IDs"}}]},{"text":" for a full list of availabel CM variables. The management interface has following functions:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Responding to scan requests for devices","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Listing CM variables","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Reading CM variables","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Writing CM variables","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Setting IP address","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Wink command","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Each of those functions can be permanently disabled by setting a bit in the CM variable GOAL_ID_DD:FEATURE_DISABLE.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Firmware Update","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Update the communication controller","type":"text"}]},{"type":"paragraph","content":[{"text":"Firmware update of the communiation controller is possible using HTTP. It is done using the ","type":"text"},{"text":"Industrial Communication Explorer","type":"text","marks":[{"type":"link","attrs":{"href":"https://portgmbh.atlassian.net/wiki/spaces/ICE"}}]},{"text":". This tool uses the HTTP protocol to transfer a firmware package to the device. ","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Firmware package","type":"text"}]},{"type":"paragraph","content":[{"text":"Firmware image","type":"text","marks":[{"type":"link","attrs":{"href":"https://portgmbh.atlassian.net/wiki/spaces/IRJ45SOM/pages/1097728001"}}]},{"text":" 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. ","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Control interface","type":"text"}]},{"type":"paragraph","content":[{"text":"By default, a firmware update is possible at any time. The System-on-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.","type":"text"}]},{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"appl_ccmFwUpdateCbReg()","type":"text","marks":[{"type":"code"}]},{"text":". ","type":"text"}]},{"type":"codeBlock","attrs":{"language":"c"},"content":[{"text":"/****************************************************************************/\n/** firmware update callback\n *\n */\nstatic void appl_fwUpdateCb(\n FW_UPDATE_SOURCE_T source, /**< fw update source */\n FW_UPDATE_STATUS_T state, /**< fw update status */\n uint8_t progress /**< fw update progress */\n)\n{\n switch (state) {\n default:\n case FW_UPDATE_IDLE:\n goal_logInfo(\"fw update state : IDLE\");\n break;\n case FW_UPDATE_TRANSFER_INIT:\n goal_logInfo(\"fw update state : TRANSFER INIT\");\n switch (source) {\n case FW_UPDATE_SOURCE_RPC:\n goal_logInfo(\"fw update source : RPC\");\n break;\n case FW_UPDATE_SOURCE_HTTP:\n goal_logInfo(\"fw update source : HTTP\");\n break;\n case FW_UPDATE_SOURCE_FOE:\n goal_logInfo(\"fw update source : FOE\");\n break;\n }\n break;\n case FW_UPDATE_TRANSFER:\n goal_logInfo(\"fw update state : TRANSFER, progress = %d\", progress);\n break;\n case FW_UPDATE_TRANSFER_DONE:\n goal_logInfo(\"fw update state : TRANSFER DONE\");\n\n goal_logInfo(\"performing update, rebooting CCM module\");\n /* perform actual update */\n appl_ccmFwUpdateExecute();\n break;\n case FW_UPDATE_ABORT:\n goal_logInfo(\"fw update state : ABORT\");\n break;\n case FW_UPDATE_COMMIT_PENDING:\n goal_logInfo(\"fw update state : PENDING\");\n break;\n case FW_UPDATE_COMMIT_DONE:\n goal_logInfo(\"fw update state : UPDATE DONE\");\n break;\n }\n}","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Firmware update sequence","type":"text"}]},{"type":"paragraph","content":[{"text":"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: ","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"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.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"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.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Keep update functionality while disabling DD","type":"text"}]},{"type":"paragraph","content":[{"text":"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: ","type":"text"}]},{"type":"paragraph","content":[{"text":"1. Disabling DD by default","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"},{"type":"hardBreak"},{"text":"Internally this value is stored to the CM variable FEATURE_DISABLE, which state also can be saved permanently to flash.","type":"text"}]},{"type":"paragraph","content":[{"text":"2. Introducing a switch to termporarily enable DD features","type":"text"}]},{"type":"paragraph","content":[{"text":"If a firmware update shall be processed, minimal DD features need to be set temporarily. These are:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"HELLO REQUEST","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"SET CONFIG","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"GET CONFIG","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"SET IP","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"This can be done using the API function goal_ddSessionFeatureActivate() with the following arguments: ","type":"text"}]},{"type":"codeBlock","content":[{"text":"goal_ddSessionFeatureActivate(pHdlDd, GOAL_DD_FEAT_GETCONFIG | GOAL_DD_FEAT_SETCONFIG | GOAL_DD_FEAT_SETIP);","type":"text"}]},{"type":"paragraph","content":[{"text":"The temporary switch, to enable the management interface, can be implemented using the web server. See example ","type":"text"},{"text":"01_pnio_io_mirror","type":"text","marks":[{"type":"link","attrs":{"href":"https://portgmbh.atlassian.net/wiki/spaces/IRJ45SOM/pages/169312303"}}]},{"text":" 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. ","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Update possibilities for application controller","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"},{"type":"hardBreak"},{"text":"Following, two possible solutions are shown:","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"AC Firmware update over HTTP","type":"text"}]},{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"goal_http/02_post","type":"text","marks":[{"type":"em"}]},{"text":", respectively ccm example ","type":"text"},{"text":"20015013_irj45/01_pnio_io_mirror","type":"text","marks":[{"type":"em"}]},{"text":" can be used. ","type":"text"},{"type":"hardBreak"},{"text":"For the latter, data for firmware update transported using a HTTP POST request will be processed in the callback function ","type":"text"},{"text":"httpDataCbPost","type":"text","marks":[{"type":"code"}]},{"text":", for example as shown in the following sample code: ","type":"text"}]},{"type":"codeBlock","attrs":{"language":"c"},"content":[{"text":"/****************************************************************************/\n/**\n * This is the http application callback.\n *\n * @retval GOAL_OK on success\n * @retval GOAL error code otherwise\n */\nstatic GOAL_STATUS_T goal_http_cb(\n GOAL_HTTP_APPLCB_DATA_T *pCbInfo /**< callback info */\n)\n{\n GOAL_STATUS_T res = GOAL_OK; /* return value */\n static uint8_t data[32]; /* test data */\n static uint8_t lenData = 0; /* test data length */\n unsigned int lenCopy = 0; /* length for copying data */\n\n /* check resource handle */\n if (hdlRes != pCbInfo->hdlRes) {\n /* error */\n goal_logErr(\"Requested resource does not match\");\n res = GOAL_ERROR;\n }\n\n if (GOAL_RES_OK(res)) {\n /* check requested method */\n switch (pCbInfo->reqType)\n {\n case GOAL_HTTP_FW_GET:\n if (0 == GOAL_MEMCMP(pCbInfo->cs.pUrl, \"/index.html?data\", GOAL_STRLEN(\"/index.html?data\"))) {\n /* return test data */\n GOAL_HTTP_GET_RETURN_RAW(pCbInfo, data, lenData);\n } else {\n /* set information for send function */\n GOAL_HTTP_GET_RETURN_HTML(pCbInfo, pageIndex, GOAL_STRLEN((const char *) pageIndex));\n }\n break;\n\n case GOAL_HTTP_FW_POST_START:\n goal_logInfo(\"Start of POST request reached application\");\n /* reset test data */\n GOAL_MEMSET(data, 0, sizeof(data));\n lenData = 0;\n /* return html code \"204 no content\" */\n GOAL_HTTP_RETURN_OK_204(pCbInfo);\n break;\n\n case GOAL_HTTP_FW_POST_DATA:\n goal_logInfo(\"Data chunk of POST request reached application\");\n /* calculate length for copying data */\n if (lenData < sizeof(data)) {\n if (pCbInfo->cs.lenData < (sizeof(data) - lenData)) {\n lenCopy = pCbInfo->cs.lenData;\n } else {\n lenCopy = sizeof(data) - lenData;\n }\n /* update recent data length */\n lenData += lenCopy;\n }\n /* copy testdata */\n GOAL_MEMCPY(data, pCbInfo->cs.pData, lenCopy);\n /* return html code \"204 no content\" */\n GOAL_HTTP_RETURN_OK_204(pCbInfo);\n break;\n\n case GOAL_HTTP_FW_POST_END:\n goal_logInfo(\"End POST request reached application\");\n /* return html code \"204 no content\" */\n GOAL_HTTP_RETURN_OK_204(pCbInfo);\n break;\n\n case GOAL_HTTP_FW_REQ_DONE_OK:\n case GOAL_HTTP_FW_REQ_DONE_ERR:\n /* send info message */\n goal_logInfo(\"Transmission done\");\n GOAL_HTTP_RETURN_OK_204(pCbInfo);\n break;\n\n default:\n break;\n }\n }\n\n return res;\n}","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"AC Firmware update over TCP","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"Respectively, following callback function will handle received data: ","type":"text"}]},{"type":"codeBlock","attrs":{"language":"c"},"content":[{"text":"/****************************************************************************/\n/** TCP Server Callback\n *\n * Print a hexdump of the received data.\n */\nstatic void tcpCallback(\n GOAL_MA_CHAN_TCP_T *pMaTcpHdl, /**< MA handle */\n GOAL_NET_CB_TYPE_T cbType, /**< callback type */\n struct GOAL_NET_CHAN_T *pChan, /**< channel descriptor */\n struct GOAL_BUFFER_T *pBuf /**< GOAL buffer */\n)\n{\n GOAL_NET_ADDR_T remote; /* remote address */\n GOAL_STATUS_T res; /* result */\n\n if (cbType == GOAL_NET_CB_NEW_SOCKET) {\n goal_logInfo(\"new TCP socket from TCPListener: %p\", (void *) pChan);\n\n /* get IP Address of remote node */\n res = goal_maChanTcpGetRemoteAddr(pMaTcpHdl, pChan, &remote);\n if (GOAL_RES_ERR(res)) {\n goal_logErr(\"Failed to get Remote Address for socket %p\", (void *) pChan);\n return;\n }\n\n goal_logInfo(\"sender 0x%08\"FMT_x32\":%u\", remote.remoteIp, remote.remotePort);\n }\n else if (cbType == GOAL_NET_CB_NEW_DATA) {\n goal_logDbg(\"Data received on tcp socket %p\", (void *) pChan);\n\n /* echo message or process data */\n goal_maChanTcpSend(pMaTcpHdl, pChan, pBuf);\n\n }\n else if (cbType == GOAL_NET_CB_CLOSING) {\n goal_logInfo(\"Closing TCP socket %p\", (void *) pChan);\n }\n}","type":"text"}]}],"version":1}