How Can We Help?

Print

ACE-MQTT-4G Gateway: System Functions

 

In the Gateway > MQTT Configuration menu, you can define certain MQTT topics for the system functions.

The 6 predefined functions

  • Certificate_Update : Remotely update the SSL/TLS certificate
  • MQTT_Config_Update : Remotely update the MQTT configuration
  • Firmware_Update : Remotely update the firmware
  • ACE_PLC_Update : Remotely update the ACE PLC program with the file generated by the vBuilder software
  • GTW_Parameter_Update : Remotely update a MQTT parameter
  • ACE_FTP_Upload : Download a file from the GTW to an FTP server. Here it concerns the log file.

Before upgrading remotely, it is strongly advised to test locally with the same configuration, unless your Gateway is close to your workplace!

General functional principle

  • The new files concerned by the updatre must be installed on a remote http server
  • The trigger to launch the update is an MQTT PUB from an MQTT client
  • The Payload of this PUB contains the necessary elements to allow the Gateway to update itself. Maybe depending on the type of update:
    • the http link to the http server
    • and/or the password to decompress the encrypted zip file
    • and/or all parameters required to process the update

Update process(es) : Follow and read each step carefully!

Certificate_Update

Remote update of the SSL/TLS Certificate (ca.crt file)

This system function allows you to remotely update the SSL/TLS certificate by replacing the existing certificate with a new one.

A restart of the MQTT process will be performed after the update.

It is important to use the same file name to make sure it matches the file name defined in the MQTT TLS settings

  • MQTT_Topic_to_Sub_for_Parameter:
    • The one you want. Example: update/ace-gtw-4g/certificat
    • Attention, the common prefix and suffix in the [MQTT Topics] tab for the Modbus topics are not added for system functions topics: Add them if need.
  • Predefined_Name_of_the_Function:
    • Must be: Certificate_Update
  • Certificate file
    • The ca.crt file must be in the remote HTTP directory
    • The ca.crt file must be zipped with a password.
      • You can use 7-Zip software (see “How to use the 7-Zip software” at the bottom of the page)
    • The result must be ca.crt.zip file with inside your *.crt file
    • Inside the zip file, its file name must be the same than the file name define in the MQTT Broker configuration (path is always /etc/luci-uploads)
  • MQTT Payload to be send from another MQTT Client for start udpate:
    • HTTP link to the file directory (not to the file name!)
      • Example: https://www.support.aceautomation.eu/gtw-mqtt-4g/mqtt-files
      • No forward slash ” / ” at the end of the URL
    • Space ( )
    • Password with single quotes (‘)
      • Example: '6UnJS%#n!3u632^cEs2mgvq'
    • Full example:
      • https://www.support.aceautomation.eu/gtw-mqtt-4g/mqtt-files '6UnJS%#n!3u632^cEs2mgvq'

 

MQTT_Config_Update

This system function allows you to remotely update the MQTT configuration (mqtt file) by replacing the existing file with a new one.

A restart of the MQTT process will be performed after the update.

It is important to check your configuration to make sure it matches with all remote parameters. Check theses points :

  • The MQTT client’s ID must certainly be the same
  • Path of the Topics Modbus and Topics functions: They can include the MQTT client’s ID.
  • Common tag prefix/suffix for PUBs and SUBs: They can include the MQTT client’s ID.

Process the remote update of the MQTT configuration (mqtt file)

  • MQTT_Topic_to_Sub_for_Parameter:
    • The one you want. Example: update/ace-gtw-4g/mqtt
    • Attention, the common prefix and suffix in the [MQTT Topics] tab for the Modbus topics are not added for system functions topics: Add them if need.
  • Predefined_Name_of_the_Function:
    • Must be: MQTT_Config_Update
  • MQTT file
    • The mqtt file must be in the remote HTTP directory
    • The format must be the same as in Gateway > MQTT Config File menu: Text format.
    • Its name must be always mqtt (without extenion)
    • The mqtt file must be zipped with a password.
      • You can use 7-Zip software (see “How to use the 7-Zip software” at the bottom of the page)
    • The result must be mqtt.zip file with inside mqtt file
    • Its name must be always “mqtt“
  • MQTT Payload to be send from another MQTT Client for start udpate:
    • HTTP link to the file directory (not to the file name!)
      • Example: https://www.support.aceautomation.eu/gtw-mqtt-4g/mqtt-files
      • No forward slash ” / ” at the end of the URL
    • Space ( )
    • Password with single quotes (‘)
      • Example: '6UnJS%#n!3u632^cEs2mgvq'
    • Full example:
      • https://www.support.aceautomation.eu/gtw-mqtt-4g/mqtt-files '6UnJS%#n!3u632^cEs2mgvq'

Firmware_Update

Process the remote update of the ACE-GTW-4G firmware (firmware.bin and sha256sums files)

  • MQTT_Topic_to_Sub_for_Parameter:
    • The one you want. Example: update/ace-gtw-4g/firmware
    • Attention, the common prefix and suffix in the [MQTT Topics] tab for the Modbus topics are not added for system functions topics: Add them if need.
  • Predefined_Name_of_the_Function:
    • Must be: Firmware_Update
  • Firmware file
    • The firmware and sha256sums files must be in the remote HTTP directory
    • Their file names should always firmware.bin and sha256sums
    • firmware.bin must be compatible with the ACE-GTW-4G Gateway (test it before remote update !)
    • sha256sums must contain this text:
      • serial-sha-256-key */tmp/firmware.bin
      • Example: d61eeb18eedbfe8ebe56991f3424a9c52c33b0bc0dd0f8e1e05556c3fc541ee1 */tmp/firmware.bin
      • With a carriage return (CR) at the end of the line ([Enter])
      • The key number depends on the firmware file
      • This file is provided with the firmware (ask us if necessary)
    • The result must be firmware.bin and sha256sums files inside the remote HTTP directory (not zipped)
  • MQTT Payload to be send from another MQTT Client for start udpate:
    • HTTP link to the file directory (not to the file name!)
      • Example: https://www.support.aceautomation.eu/gtw-mqtt-4g/firmware-files
      • No forward slash ” / ” at the end of the URL

ACE_PLC_Update

Process the remote update of the ACE PLC program (aceprogram.vCompiled file)

  • MQTT_Topic_to_Sub_for_Parameter:
    • The one you want. Example: update/ace-gtw-4g/plc-program
    • Attention, the common prefix and suffix in the [MQTT Topics] tab for the Modbus topics are not added for system functions topics: Add them if need.
  • Predefined_Name_of_the_Function:
    • Must be: ACE_PLC_Update
  • ACE program file
    • The ACE program file must be in the remote HTTP directory
    • The format must be:
      • .vCompiled. See in vBuilder, Tools > Program To File menu
      • Its name must be always aceprogram.vCompiled
    • The “aceprogram.vCompiled” file must be zipped with a password.
      • You can use 7-Zip software (see “How to use the 7-Zip software” at the bottom of the page)
    • The result must be always aceprogram.zip file with inside aceprogram.vCompiled file
  • MQTT Payload to be send from another MQTT Client for start udpate:
    • HTTP link to the file directory (not to the file name!)
      • Example: https://www.support.aceautomation.eu/gtw-mqtt-4g/ace-files
      • No forward slash ” / ” at the end of the URL
    • Space ( )
    • Password with single quotes (‘)
      • Example: '6UnJS%#n!3u632^cEs2mgvq'
    • Full example:
      • https://www.support.aceautomation.eu/gtw-mqtt-4g/ace-files '6UnJS%#n!3u632^cEs2mgvq'

The MQTT process is stopped while the ACE program is being updated, then the whole thing restarts (MQTT process and ACE PLC program)

 

GTW_Parameter_Update

This system function allows you to remotely update one parameters of the MQTT configuration (mqtt file) by replacing the existing parameter with a new one.

A restart of the MQTT process will be performed after the update.

It is important to check the parameter you want to update. Otherwise, with a wrong parameter, you can no longer have access to your Gateway

Process the remote update of a MQTT parameter (mqtt file)

  • MQTT_Topic_to_Sub_for_Parameter:
    • The one you want. Example: update/ace-gtw-4g/parameter
  • Predefined_Name_of_the_Function:
    • Must be: GTW_Parameter_Update
  • You need to know :
    • ( 1 ) the name of the section (mqttconfig or topics or systopics or..)
    • The index of this section which start from 0.
    • ( 2 ) the name of the option concerned (projectname)
    • ( 3 ) the new desired value for this parameter
  • MQTT Payload to be send from another MQTT Client for start udpate:
    • The Payload for the Topics system will be composed with:
      • mqtt.@section[index].option ‘value‘
      • Example:
        • mqtt.@mqttconfig[0].projectname 'My New Project name'
    • For multiples sections (topics or systopics or..) with the same name, you must specify the right index, which mean you must know its position in the MQTT file.
      • Example for modify the slaveid of the 2nd topics, from 1 to 5:
        • mqtt.@topics[1].slaveid '5'

 

ACE_FTP_Upload

Download a file from the GTW to an FTP server. Here it concerns the log file.

  • MQTT_Topic_to_Sub_for_Parameter:
    • The one you want. Example: update/ace-gtw-4g/ftp-log
    • Attention, the common prefix and suffix in the [MQTT Topics] tab for the Modbus topics are not added for system functions topics: Add them if need.
  • Predefined_Name_of_the_Function:
    • Must be: ACE_FTP_Upload
  • FTP Server

    • You need to install or already have an FTP server available, with its
      • ftp address
      • ftp user login
      • ftp user password
  • MQTT payload to be sent by another MQTT client to receive log files on your FTP server
    • log FTP_file_directory “username:password”

      • Example: log ftp://ftp.myftplink.eu/ "mylogin:mypassword"
        • At each PUBlication, the GTW sends its log file to the FTP server
        • log, means log file. Other file names will be available at a later date.

 

Help in solving problems encountered

  • If you have space(s) in your http link, add quote and/or replace space by %20
    • 'https://www.support.aceautomation.eu/gtw-mqtt-4g/ace%20files' '6UnJS%#n!3u632^cEs2mgvq'
    • The quote should be like the example above, not like ‘ or ” (cut/paste often changes the type of quote)
  • Be carreful to add the full link with http://www… or https://www…
  • The names of the files are imposed
    • For the .zip file
    • and the files inside the zip file
  • Check the synthaxe of your Topic name when you send the Payload from your MQTT Client
    • Common tag prefix and suffix are not add for this system functions
  • Files must be installed on a HTTP or HTTPS server
  • Always use a password for the zip files
  • No forward slash ” / ” at the end of the URL (if exist)

 

How use 7-Zip software

  • Archive format: zip with the right file name
  • Enter a password