Tunnel – Special AT Commands (API)
¿Buscas alguna otra cosa?
MTX-Tunnel needs special proprietary AT commands to allow MTX-Tunnel to be controlled by a third-party application, using a local serial port or 2G/3G/4G connection remotely. Please remember you can use one or two of the COM serial ports available. You can use them locally or you can use them remotely with IP (webserver, Telnet, MQTT, SNMP, gateway, etc.) and also SMS text messages. Please read carefully this AT special commands set features:
AT^MTXTUNNEL=END
This command stops and ends MTX-Tunnel Java program execution. MTX-Terminal modem is now in normal mode. This allows certain intelligent devices connected to MTX-Terminal to run or stop the MTX-Tunnel application and use the modem terminal for a voice call, CSD call, firmware upgrade… after this, MTX-Tunnel can be run again.
AT^MTXTUNNEL=VERSION
String returned is version information. Only for MTX-Tunnel V7 and above.
AT^MTXTUNNEL=SETBAUDRATE,port,speed
This command can change the modem serial port speed for a temporary amount of time, without the need for MTX-Tunnel to be reset. EXAMPLE AT^MTXTUNNEL=SETBAUDRATE, 0, 9600 ASC0 port baud rate speed is now 9600 bauds. AT^MTXTUNNEL=SETBAUDRATE, 1, 19200 ASC1 port speed is now 19200 bauds. Only for MTX-Tunnel V7 and above
AT^MTXTUNNEL=GETPARAM,parameter_name
This command is intended to read or to find out a configuration parameter stored in a configuration file inside –non volatile memory-. For example, to read APN value stored in configuration file, use: AT^MTXTUNNEL=GETPARAM, GPRS_apn
AT^MTXTUNNEL=GETCONFIG
This command is available for versions of MTX-Tunnel after v7.15. It returns the configuration file config. txt, avoiding the need for repeated use of AT^MTXTUNNEL=GETPARAM.
AT^MTXTUNNEL= SETPARAM,parameter_name,ValueParametro
This command is used to change any MTX-Tunnel configuration parameter value. For example, to change the baud rate of COM1 to 9600 bauds: AT^MTXTUNNEL=SETPARAM, COMM_baudrate, 9600 Please be sure to reset the MTX-Tunnel application to get the new configuration. The AT command to reset the terminal is AT+CFUN=1, 1
AT^MTXTUNNEL= SETPARAM,parameter_name1:parameter_value1\r\nparameter_name2:parameter_value2|r\n.....parameter_nameN:parameter_valueN}
This command is used to change several parameter values at the same time. AT^MTXTUNNEL=SETPARAMS,{COMM_baudrate:9600\r\nCOMM_bitsperchar:8} Please be sure to reset the MTX-Tunnel application to get the new configuration. The AT command to reset the terminal is AT+CFUN=1, 1
AT^MTXTUNNEL=GETIOS
This command gets readings from all GPIOs and ADCs of MTX-Terminals with MTX-Tunnel running. This is more convenient and faster than using one AT command for each GPIO/ADC, especially if you use SMS or GPRS connection for this. After execution, this AT command responds with each value in following order. Every state is separated by a “,” character: GPIO1,GPIO2,GPIO3,GPIO4,GPIO5,GPIO6,GPIO7,GPIO8,GPIO9,GPIO10,ADC1,ADC2
AT^MTXTUNNEL=GETIO,numGPIO
This command returns the value of a digital input. NumGPIO indicates the GPIO number (1 to 10). Refer to GPIOs in the tables at the end of this manual for more information.
AT^MTXTUNNEL=GETADC,numADC
This command returns the value of a particular analog input. NumADC indicates the number of ADC (1,2). Refer to ADCs in the tables at the end of this manual for more information.
AT^MTXTUNNEL=RS232,mode,data
This command allows you to send and receive data directly from an MTX-Tunnel serial port. This is useful for end applications using WEB page forms; you can get the form values from the web page, collect them in the serial port, and after using them, send a response to the web page. You can see in Annex an example. Mode values: 0, 1, 2 or 3.
- 0: data is forwarded through COM1 without waiting for a response from the device connected to COM1, so there is no value response to this AT command.
- 1: data is forwarded through COM1 and will wait for a response from the device connected to COM1. This response will be the return value of this AT command.
- 2: data is forwarded through COM2 without waiting for a response from the device connected to COM2, so there is no value response to this AT command.
- 3: data is forwarded through COM2 and will wait for a response from the device connected to COM2. This response will be the return value of this AT command.
NOTE Mode value 1 and 3. Maximum device response is 160 characters long. data parameter is a text string sent though serial port.
AT^MTXTUNNEL=SMS,phone_number,message
This proprietary AT command is intended to send SMS text messages. Do not use the AT+CMGS command as it is intended to be used in end-party applications. Parameters description: “phone number”: End user’s phone number “message” SMS text string
AT^MTXTUNNEL=SETMODBUS,address;position1;data_1;data_2;...;data_n
When a MODBUS device is connected to secondary port on MTXTerminal, this proprietary AT command will allow some parameters stored in the memory table to change: address: modbus device address (0 … 255) position1: first position to write in modbus memory table data_1, data_2: data to be written in the Modbus on pointed position1 parameter Important: address, position1 and data_n are separated by “;”
AT^MTXTUNNEL=SETMODBUS2,address;position1;command;data_1;data_2;...;data_n
When a MODBUS device is connected to secondary port on MTX-Tunnel, this proprietary AT command will allow some parameters stored in the memory table to change: address: modbus device address (0 … 255) position1: first position to write in modbus memory table command: it indicates the command to be used. It can be the command 15 (coils) or 16 (registries) data_1, data_2: data to be written in the Modbus on pointed position1 parameter Important: address, position1 and data_n are separated by “;”. This command can use the modbus command 15 or 16.
AT^MTXTUNNEL=GETMODBUS,address;position;numData;command
When a MODBUS device is connected to a secondary port on MTXTerminal, this proprietary AT command will allow you to read some parameters stored in the memory table: address: modbus device address (0 … 255) position: first position to write in modbus memory table numData: number of data to read from modbus table command: you can use the modbus command 3 or 4 Important: address, position and numData are separated by “;”
AT^MTXTUNNEL=GETMODBUSALL
In this guide you will find many examples of scenarios where MTX-Tunnel is configured to read periodically the registries of one or many modbus slave devices. For example, you could configure MTXTunnel to read X devices every hour. But if at some point you want to launch a reading of all the Modbus devices configured (for example to make a test without waiting for 1 hour until the event happens) you can execute this AT command. It will immediately launch the process of modbus reading and sending the data to the server.
AT^MTXTUNNEL=TEMPORALCLIENT,IPaddress,TCPport,seconds
A new AT command that can create a temporal client TCP socket to a specific server IP address and port. Only use this when the MTX_mode parameter is “server” or “none”. Now you can send AT commands remotely, by simply using the special tags <MTXTUNNELR></MTXTUNNELR> Parameters: IPaddress: IP address (server) to be connected TCPport: TCP to be connected IMPORTANT. TEMPORAL client socket means it will be closed automatically if GPRS data is not sent or received within 60 seconds. The “seconds” parameter is available for versions of MTX-Tunnel after v7.15. It allows you to specify the number of seconds during which the socket will be open. If the command is resent with the seconds parameter as “0” once the socket is established, the temporal socket is immediately closed, without waiting for it to finish.
AT^MTXTUNNEL=DELETEBBDD
Use this command when you need to delete the datalogger internal memory on MTX-Tunnel. After using it, the internal modem memory file “data.txt” will be deleted and the MTX-Terminal modem will be reset.
AT^MTXTUNNEL=SETIO,X,Y
MTX terminals that use 3G technology do not allow the use of the command AT^SSIO which is used in GPRS terminals to change a digital input. Instead, AT^MTXTUNNEL=SETIO,X,Y is to be used, where X is the GPIO to be changed (0,…,9) and Y the value to be assigned (0, 1)
AT^MTXTUNNEL=FTP, ftpServer, loginServerFTP, passwordServerFTP, directoriyFTP, remoteFilename, MTXFilename, NotificationURL
A FTP from a file saved on a remote server can be downloaded onto the MTX terminal, which can be used to change the configuration files “config.txt” and “operators.txt” or to download other times of files.
The server login and password must be inputted, along with the server directory where the file is located, its name in the server and the name to be used in the MTX device, and a URL that is notified when the download is carried out correctly.
EXAMPLE:
at^mtxtunnel=FTP,ftp.mydomain.com,myUser,myPass,folder1/folder2/,config.txt,config.txt,
AT^MTXTUNNEL=DOWNLOAD,http://www.myDomain.es/myPath,myUsername,myPassword,myOriginFile,myDestinationPath,myDestinationFile,timeOut
It is possible to make an HTTP/HTTPS download of a file set on a web server in the MTX terminal. It is useful to change the configuration file “config.txt”, change the file “iperators.txt” or download other kind of file.
EXAMPLES
AT^MTXTUNNEL=DOWNLOAD,http://myDomain.com/myPath,myUser,myPass,config. txt,,config.txt,30
AT^MTXTUNNEL=DOWNLOAD,http://myDomain.com/myPath,myUser,myPass,ServerCertificate1.jar,security/certs/servers/,ServerCertificate1.jar,30
Remember that if you change the configuration remotely, you must restart the MTX so it loads the new configuration (command AT+CFUN=1,1).
The time base for the timeOut parameter is seconds. This command will return OK or ERROR after downloading the file, not being able to send another command until the end of the same (download or timeout).
AT^MTXTUNNEL=ADOWNLOAD,http://www.myDomain.es/myPath,myUsername,myPassword,myOriginFile,myDestinationPath,myDestinationFile,timeOut
It is possible to perform an asynchronous HTTP / HTTPS download of a file located on a web server in the MTX terminal. Useful to change the configuration file “config.txt”, change the file “operators.txt” or download another type of file.
EXAMPLES
AT^MTXTUNNEL=ADOWNLOAD,http://myDomain.com/myPath,myUser,myPass,config.txt,,config.txt,30
AT^MTXTUNNEL=ADOWNLOAD,http://myDomain.com/myPath,myUser,myPass,ServerCertificate1.jar,security/certs/servers/,ServerCertificate1.jar,30
Remember that if you change the configuration remotely, you must restart the MTX for it to take the new configuration (command AT + CFUN = 1,1).
The time base for the timeOut parameter is seconds. This command will return OK or ERROR immediately while the file is downloaded in the background. Use the command AT ^ MTXTUNNEL = ISFILE to find out if the file has been downloaded.
AT^MTXTUNNEL=ISFILE,path,fileName
It allows to find out if there is a file inside the modem. Useful to use in conjunction with the AT ^ MTXTUNNEL = ADOWNLOAD command.
EXAMPLE
AT^MTXTUNNEL=isfile,,config.txt
This command will return OK if the file exists or ERROR if it does not exist.
If the file is in the root directory, leave the path field blank.
AT^MTXTUNNEL=SETCONFIGFILE,{ConfigRaw}
This command allows the entire content of MTX-Tunnel’s configuration file to be established without having to change each parameter one-by-one. It is designed to be used only from a Web platform as a response to the sending of a JSON object. For example, when MTX sends a JSON object from its internal logger to a Web platform, it can receive this command as a response between the <MTXTUNNELR> and </MTXTUNNELR> to change the complete configuration.
MTX will restart with the new configuration once the AT command is processed. The configuration must be between the {} tags.
The parameters can be sent separated by the sign “\r\n”.
EXAMPLE
{COMM_baudrate:9600\r\nCOMM_bitsperchar:8\r\n …………………}
AT^MTXTUNNEL=SETOUTPUTTIMER,numOutput,value
This command allows a digital input or relay to be activated for X seconds using just one AT command. The output must be pre-configured with OUTPUT_mode in Timer mode (see example 8.5). numOutput is a value from 0 to 3, depending on the MTX model. Value can be either 0 or 1. The following AT commands are only used if the MTX_portAux value is configured to “wavenis”. You use it when MTX-IND-V1 and MTX-IND-V2 terminal modems are used with internal Wavenis card for concentrator scenario purposes and to allow communication via radio, with the modem and remote card sensor using Wavenis protocols.
AT^MTXTUNNEL= GETPOWERSTATUS
Command to state whether a MTX modem is being powered by an external power supply or by an internal battery. Only for modems with internal battery. Possible responses: -1 (ERROR), 0 (internal battery functioning), 1 (external power supply functioning).
AT^MTXTUNNEL= GETCELLID
Returns the identificator of the telephone cell being used. Useful for gsm localization systems.
AT^MTXTUNNEL= RESET,time
Resets the modem after the specific number of seconds indicated in “time” parameter (0, … 86400).
AT^MTXTUNNEL= getCounter,numCounter
Returns the current value of numCounter. The parameter “numCounter” can be 0 (in order to read counter number 1) or 1 (in order to read counter number 2). The returned value by the command is a value between 0 and 4294967294. Command exclusively valid for MTX-xG-Java-IoT.
AT^MTXTUNNEL= setCounter,numCounter,value
Sets the current value of a pulse counter. The parameter “numCounter” can be 0 (in order to update counter number 1) or 1 (in order to read counter number 2). The “value” field may have a value between 0 and 4294967294. Command exclusively valid for MTX models with pulse input counters like MTX-Java-IOT.
AT^MTXTUNNEL= setSchedule,ID:Day;Hour;Minute;ATCommand
Allows to configure an AT timing command for it to be executed on a certain day of the week (Monday, … Sunday) at a certain hour and minute. For example, it may be of use if you want to switch a relay or a digital output at certain hours. Remember that the modem uses UTC time. ID: 1 … 200. Timing index. 200 timings maximum. Day: 1…7. (1= Monday, 2=Tuesday, … , 7 = Saturday) Hour: 0…23 Minute: 0…59 ATCommand: execute AT Command EXAMPLE AT^MTXTUNNEL=setSchedule,1:2;22;0;AT^SSIO=0,1 (activates GPIO1 digital output every Tuesday at 22:00) This command will write to a file named “schedule.txt” that is inside the modem. There is also the possibility of upload the file into the modem by using a FTP server and the command AT^MTXTUNNEL=FTP, … The above mentioned “schedule.txt” file has the following format: 1:day;hour;minute;ATcommand 2:day;hour;minute;ATcommand 3:day;hour;minute;ATcommand If you want to delete a certain time setting, you can use “null” key in ATCommand field. For example, if you want to delete timing with ID=1: AT^MTXTUNNEL=setSchedule,1:2;22;0;null
AT^MTXTUNNEL=getSchedule,ID
Returns ID schedule of the modem, where ID = 1…200 indicates the schedule number.
AT^MTXTUNNEL=getSchedules
Returns a list with all scheduled time settings.
AT^MTXTUNNEL=delSchedules
Deletes all scheduled time settings.
AT^MTXTUNNEL=getAstronomic,latitude,longitude,dd,mm,yyyy
Returns the Ortho and Sunset for a given latitude, longitude, day, month, and year. Example for the city of Madrid: AT^MTXTUNNEL=getAstronomic,40.4893,-3.6827,12,03,2017
AT^MTXTUNNEL=SETULPSECONDS,value
Command only for MTX models with ULP (Ultra Low Power). This command allows, once the modem is awake, to increase the time it stays awake or finish immediately. For example, you want to wake up the modem just 5 minutes every day to perform a task. The modem awakes and the task is completed in 2 minutes. Instead of waiting the remaining 3 minutes to enter ULP mode again, it can be shut down immediately specifying value 0, saving power. value: 0 … 86400 seconds
AT^MTXTUNNEL=CERTIFICATE,LISTSERVERS
It lists user SSL Root CA certificates for SSL connections. It lists the files available in the folder “secutity/certs/servers,” that is up to 10 possible files ServerCertificate1.jar, … ServerCertificate10.jar.
AT^MTXTUNNEL=CERTIFICATE,INSTALLSERVERS
It installs all user SSL Root CA certificates for SSL connections. It installs the files available in the folder “secutity/certs/servers,” that is up to 10 possible files ServerCertificate1.jar, … ServerCertificate10.jar.
AT^MTXTUNNEL=CERTIFICATE,DELETESERVER,certificateFile
It eliminates the SSL Root CA certificate indicated. The parameter “certificateFile” indicates one of the 10 possible certificate files ServerCertificate1.jar, … ServerCertificate10.jar that can be found in the directory “secutity/certs/servers” inside the modem. Once the command is executed the certificate is uninstalled and the file deleted from the directory.
AT^MTXTUNNEL=CERTIFICATE,LISTCLIENTS
It lists client certificates for SSL connections (only needed if certificate client authentication is required from the server). It lists the files available in the folder “secutity/certs/servers,” that is up to 10 possible files ServerCertificate1.jar, … ServerCertificate10.jar.
AT^MTXTUNNEL=CERTIFICATE, INSTALLCLIENT,certificateFile
Unlike the certificates on the server, for which it is possible to install up to 10 at the same time, in the case of the client certificate, for obvious reasons it is only possible to install one certificate at a time. With this command it is specified the certificate to install.
AT^MTXTUNNEL=CERTIFICATE,DELETECLIENT
It uninstalls the client certificate (but unlike the server certificate, it doesn’t delete any file from the directory “secutity/certs/servers”).
AT^MTXTUNNEL=CERTIFICATE,DELETEFILECLIENT,certificateFile
It deletes the indicated certificate from the directory “secutity/certs/servers.”
AT^MTXTUNNEL=setAstroSchedule,ID:Day;Month;SunriseHour;SunriseMinute; SunsetHour;SunsetMinute
Allows you to manually set the sunrise and sunset times for special days of the year (exceptions). In other words, if the astronomical clock is activated to act on a relay, it will switch based on the automatic calculations (sunrise / sunset) made by the modem, except for the times indicated by this command. This will allow you to set schedules for special days.
ID: 1 … 100. Temporization index, 100 schedules max.
Day: 1…31
Month: 1…12
SunriseHour: 0…23
SunriseMinute: 0…59
SunriseHour: 0…23
SunriseMinute: 0…59
Example:
AT^MTXTUNNEL= setAstroSchedule,1:15;7;8;30;21;45
(for July 15 the ortho will be at 8:30 and the sunset at 21:45)
This command will write to a file named “astroschedule.txt” found inside the modem. The entire copy of said file from an FTP server is also allowed using the command AT ^ MTXTUNNEL = FTP,…. Ó AT ^ MTXTUNNEL = DOWNLOAD…
The format of this file “astroschedule.txt” is as follows:
1:day;month;SunriseHour;SunriseMinute;SunsetHour;SunSetMinute\r\n
2:day;month;SunriseHour;SunriseMinute;SunsetHour;SunSetMinute\r\n
3:day;month;SunriseHour;SunriseMinute;SunsetHour;SunSetMinute\r\n
…
AT^MTXTUNNEL=getAstroSchedule,ID
Returns the special astronomical programming modem ID, where ID = 1 … 100 indicates the exception number.
AT^MTXTUNNEL=getAstroSchedules
Returns a list with all the exceptions of the astronomical clock.
AT^MTXTUNNEL=delAstroSchedules
Removes all exceptions from the astronomical clock.
AT^MTXTUNNEL=delAstroSchedule,ID
Removes all exceptions from the modem’s astronomical clock ID, where ID = 1. 100 indicates the exception number.
AT^MTXTUNNEL=DOWNLOAD,url,httpUsername,httpPassword,filename,modemPath,filenameDestination
Allows to download a file via http from a web server inside the modem.
Examples:
AT^MTXTUNNEL=DOWNLOAD,http://www.miweb.com,,,config.txt,,config.txt
AT^MTXTUNNEL=DOWNLOAD,http://www.miweb.com/miPath,,,astroschedule.txt,, astroschedule.txt
AT^MTXTUNNEL=DOWNLOAD,http://www.miweb.com/mipath,miuser,miPassord, config.txt, security/,config.txt
AT^MTXTUNNEL=IOEVENT
Starts a process of reading the modem’s I / O (digital inputs and outputs, analog inputs and pulse counters) to store them in the internal datalogger for later sending to a Web server or MQTT broker, without waiting for them to be produce an event or read period.
AT^MTXTUNNEL=GETIP
Returns the current IP address of the modem.
AT^MTXTUNNEL=EXECUTE,file
Run an AT command batch file. Inside the flash memory of the modem is a folder named “atscripts”. Batch files of AT commands can be incorporated into this folder to be executed using this command. In file the name of the file to be executed must be specified. See point 7.4 for more information.
AT^MTXTUNNEL=FORCEDNS
The DNS_ configuration parameters allow the modem to be configured to periodically send the modem status data (IP, coverage, GPIOs…). This command allows the immediate sending of the DNS frame without the need to end the configured period of time.
AT^MTXTUNNEL=SETDAC,idDAC,valor
Command that allows changing the output value of a DAC for those modem models that have this interface.
idDAC: indica el identificador del DAC (0, …)
valor: valor en milivoltios a aplicar en el DAC (0 …10100 )
AT^MTXTUNNEL=GETDAC,idDAC
Command that allows reading the output value of a DAC of those modem models that have this interface. The returned value is in millivolts.
idDAC: indica el identificador del DAC (0, …)
AT^MTXTUNNEL=SETIOMAINTENANCE,idGPIO,mode
Command that allows configuring an output type GPIO in maintenance mode. This allows you to temporarily leave the configuration mode to go into manual mode and be able to be activated / deactivated with the command AT ^ MTXTUNNEL = SETIO.
For example, consider a GPIO output configured as an astronomical clock. The output will activate with sunset and deactivate with sunrise. Activating the maintenance mode the output will go into manual mode until the maintenance mode is exited or the MTX modem is restarted.
idGPIO: indicates the identifier of the GPIO output (0, …)
mode: 0: normal working mode (the one configured in GPIO_config)
1: maintenance mode
AT^MTXTUNNEL=SETWMBUSFILTERS,value
Command that allows activating or deactivating the configured manufacturer and device filters for reading W-MBUS sensors. Useful for commissioning of facilities where the MTX-Tunnel works as a W-MBus concentrator.
value:
0: Filters disabled
1: Filters enabled