Commands¶

GSM Controller can be controlled by various commands described in this section.

Below the name of each command there is an indication where it can be used:

Console - Via the serial port, before sending the first command the access code should be given.
SMS - By sending a command in an SMS to the number of the card inserted in the device, the command must always be preceded by access code, eg 1234: reboot.
MQTT - By sending a command in an MQTT message to device's command topic (a combination of prefix and /cmd, e.g.prefix/cmd, with replies sent to prefix/cmdr).

reboot¶

Console SMS MQTT

Turns on the given output/outputs for a specified period of time.

Examples:

reboot=3,4 - turns on outputs 3 and 4 for the default time set by the time command.
reboot=0,1,3,t34 - turns on outputs 0, 1 and 3 for 34 seconds.
reboot? - reads the current status of the outputs.

on¶

Console SMS MQTT

Turns on the output/outputs.

Examples:

on=1,2,3,4,0 - turns on all outputs.
on=0 - turns on only output 0.

off¶

Console SMS MQTT

Turns off the output.

Examples:

off=1,2 - turns off the outputs 1 and 2.

time¶

Console SMS MQTT

Sets the default output on time for the reboot command when invoked without the t parameter.

Examples:

time=5 - sets the time to 5 seconds.

code¶

Console SMS MQTT

Sets an access code (1-4 characters). By default 1234.

Examples:

code=1234 - sets the code 1234.

pin¶

Console SMS MQTT

Sets a 4 digit PIN to the SIM card if the card requires a PIN. You need to set the PIN as the card has set. The command does not change the PIN on the card itself.

inpd¶

Console SMS MQTT

Reads the state of digital (logical) inputs, read-only command.

outs¶

Console SMS MQTT

Reads state of outputs, read-only command.

number¶

Console SMS MQTT

It sets one of 100 telephone numbers which will be authorized for the call function after calling the number of GSM Controller. Up to 12 digits.

Examples:

number=1:666777888 - sets the given phone number to the first position.
number?1 - reads the number from the first position.

acnumber¶

Console SMS MQTT

Sets the numbers to receive SMS notifications from events. Up to 4 numbers.

Examples:

acnumber=1:666777888 - sets the given phone number to the first position.
acnumber?1 - reads the number from the first position.

call¶

Console SMS MQTT

Sets the action for the call function, i.e. when calling the device number.

In SW 1.27 added the function of sending caller number via MQTTon topic prefix/callnum. The number must be authorized - added to the list with the number command.

Examples:

call=reboot=1,2,t3 - when calling, the reboot function will be called with given parameters.
call=on - action of turning on output 0.
call=off - action of turning off output 0.

remouts¶

Console SMS MQTT

Sets the saving of output states to be restored when the device is turned on again.

Examples:

remouts=1 - activates the function.
remouts=0 - deactivates the function.

uptime¶

Console SMS MQTT

Shows the amount of time elapsed since the device was turned on, read-only command.

name¶

Console SMS MQTT

Sets the device name (1-31 characters).

Examples:

name=restarter domowy - sets the name restarter domowy

upgrade¶

Console SMS MQTT

Starts the bootloader mode for updating the firmware. The update procedure is described here.

desanalog¶

Console SMS MQTT

Sets the SMS text for the event when getting over or below the set threshold (in the case of digital inputs it is high and low states, respectively). The first parameter defines the related reading (list of inputs in monitoron).

Examples:

desanalog=1:0:tekstPrzyUP - sets the text of the SMS when getting over the threshold for VIN.
desanalog=1:1:tekstPrzyDOWN - sets the text of the SMS when getting below the threshold for VIN.

monitoron¶

Console SMS MQTT

Activates monitoring of the given input (list of items below).

List of outputs to be monitored:

1: VIN  # measurement of supply voltage, divisor 100
2: VBAT  # measurement of battery voltage, divisor 100
3: INPA1  # measurment of analog input 1, divisor 100
4: INPA2  # measurment of analog input 2 - various sensors can be connected here (see command inpa2sensor), divisor 100
5: TEMP  # measurment of board temperature, divisor 1
6: T1  # measurment of temperature from BME280 sensor, divisor 10
7: H1  # measurment of humidity from BME280 sensor, divisor 10
8: HX711  # measurment of weight
9: DIFF  # difference of two selected measurements, divisor 10
10: DS1  # measurement of temperature from DS18B20, divisor 10
11: DS2  # measurement of temperature from DS18B20, divisor 10
12: DS3  # measurement of temperature from DS18B20, divisor 10
13: DS4  # measurement of temperature from DS18B20, divisor 10
14: DS5  # measurement of temperature from DS18B20, divisor 10
15: DS6  # measurement of temperature from DS18B20, divisor 10
16: DS7  # measurement of temperature from DS18B20, divisor 10
17: DS8  # measurement of temperature from DS18B20, divisor 10
18: P1  # measurement of humidity from BME280 sensor, divisor 100
19: INPD1  # state of digital input 1, divisor 1
20: INPD2  # state of digital input 2, divisor 1

Attention!

Measurement 9 (DIFF) does not work properly and is under construction.

Examples:

monitoron=1,2,3,4 - enables monitoring of inputs 1, 2, 3, 4.
monitoron=1 - enables input monitoring 1 - VIN.
monitoron? - returns information about which inputs are monitored.

monitoroff¶

Console SMS MQTT

Disables monitoring of the given input. The parameter defines the related reading (list of inputs in monitoron).

Examples:

monitoroff=1,2 - disables monitoring of inputs 1, 2, that is VIN, VBAT.

version¶

Console SMS MQTT

Shows the current hardware (HW) and software (SW) version, read only command.

adcprint¶

Console SMS MQTT

Displays the status of individual inputs every 2 seconds on the console.

Examples:

adcprint=1 - displays the values of VIN, PT1000, INPA1, INPA2, DTHT (DHT temperature), DTHH (DHT humidity), for the voltage to obtain the result in Volts the value must be divided by 100, for PT1000 and DHT divided by 10.
adcprint=2 - displays values directly from a 12-bit converter for analog inputs VIN, PT1000, INPA1, INPA2 (without any conversion to voltage as above), values can change from 0 to 4096, depending on the value of the measured voltage, e.g. for INPA1 - for 0 Volts will be 0, for 35V it will be close to 4096, for INPA2 - for 0 volts it will be 0, for 3.3V it will be close to 4096.
adcprint=3 - displays the values from DS18B20 sensors, the result must be divided by 10.
adcprint=0 - disables the display of the above-mentioned values.

vinread¶

Console SMS MQTT

Reads VIN (supply voltage), read-only command.

vbat¶

Console SMS MQTT

Reads VBAT (battery voltage), read only command.

inpa1read¶

Console SMS MQTT

Reads INPA1, a read-only command.

inpa2read¶

Console SMS MQTT

Reads INPA2, a read-only command.

temp¶

Console SMS MQTT

Reads module temperature, read only command.

tread¶

Console SMS MQTT

It reads the temperature from the BME280/AM2320 sensor. Read-only command.

hread¶

Console SMS MQTT

It reads the humidity from the BME280/AM2320 sensor. Read-only command.

pread¶

Console SMS MQTT

It reads the pressure from the BME280 sensor. Read-only command.

dsread¶

Console SMS MQTT

Reads values from 8 DS18B20 sensors, read-only command.

vinset¶

Console SMS MQTT

Sets the threshold value for a given input, after which, if exceeded up or down (with hysteresis), the action will be performed. Enter the values as integers (without commas), eg for VIN 1230V, enter 1230, for DS1 28.7, enter 287. The first parameter determines the related reading (list of inputs in monitoron).

Examples:

vinset=1:1230 - value 12.30V for VIN.
vinset=10:287 - the value of 28.7C for DS1.
vinset? - shows the values set for all inputs.

vinhis¶

Console SMS MQTT

Sets the hysteresis for the given input. Values should be entered as integers, eg for VIN 1.00V value 100. The first parameter specifies the related reading (list of inputs in monitoron).

Examples:

vinhis=1:100 - value 1.00V for VIN.
vinhis=10:10 - value 1.0C for DS1.

gprsapn¶

Console SMS MQTT

Sets APN, username and password for GPRS connections. Values must be entered in quotation marks.

Examples:

gprsapn="internet","user","paswd" - sets APN internet, user user, password paswd.
gprsapn="internet","","" - sets APN internet, empty name and password.

httpurl¶

Console SMS MQTT

Sets the URL to which the HTTP GET request is to be sent. You can insert readings from sensors using #XX, where XX is the number corresponding to the reading (the list is available in the description of mqttselect).

Examples:

httpurl=api.thingspeak.com/update?key=H2PN0O35KRVRG6Q0&field1=#5&field2=#6 - query to thingspeak.com with VIN and VBAT readings.

httpsend¶

Console SMS MQTT

Sends an HTTP GET request to the URL entered in httpurl.

httpautosend¶

Console SMS MQTT

Sets the period of sending HTTP GET httpurl requests.

Examples:

httpautosend=15 - sending every 15 seconds. The minimum value is 10 seconds, if it is lower than 10 but greater than 0, it will be set to 10.
httpautosend=0 - disable sending.

cusd¶

Console SMS MQTT

Runs a USSD code and returns a response.

Examples:

cusd=*100# - shows the account balance on the PLUS GSM operator card.

signal¶

Console SMS MQTT

Reads the GSM signal strength.

upinpd¶

Console SMS MQTT

Enables Pull-Up on digital input INPD1 or INPD2. When enabled, the default input state is high.

Examples:

upinpd=1,2 - INPD1 and INPD2 inputs in Pull-Up mode.
upinpd? - reads the current state.

downinpd¶

Console SMS MQTT

Disables Pull-Up on digital inputs - the default input state is low.

Examples:

downinpd=1,2 - inputs INPD1 and INPD2 are set to low by default.

restart¶

Console SMS MQTT

Restart the device.

settingsreset¶

Console SMS MQTT

Prepares the reset to defaults, which will be performed when the device is restarted, eg with the restart command.

imei¶

Console SMS MQTT

Reads IMEI of GSM modem.

debugmodem¶

Console SMS MQTT

Turns on writing out all information from GSM modem to the console.

status¶

Added in SW 1.23

Console SMS MQTT

Returns device status information such as network connection status, MQTT connection status, and modem error counts.

Examples:

status - parameterless call with an example response sim ready=1,net=2,1,mqtt_send=0, mqtt_con=1,err=0.

Description of the response:

sim ready
- sim ready=0 - problem with the card or PIN to the card
- sim ready=1 - the card is OK
net
- net=0,Y - not logged on to the network
- net=1,Y - logged on to the network
- net=2,Y - logged on to the network, GPRS/LTE connection
- net=X,0 - not logged on to the network (odczyt z modemu)
- net=X,1 - logged on to the network (odczyt z modemu)
The values of X and Y should match, except for net=2,1.
mqtt_conn
- mqtt_conn=0 - no MQTT connection
- mqtt_conn=1 - active MQTT connection
mqtt_send
- mqtt_send=0 - not in the process of sending data via MQTT
- mqtt_send=1 - is in the process of sending data via MQTT, the state should appear for a very short time (up to a few seconds), longer times mean problems with sending
err - counter of errors returned by the modem, after counting 6, the module is restarted

smssend¶

Console SMS MQTT

Sends an SMS to the indicated phone number.

Examples:

smssend=123456789:hello - sends an SMS with the text hello to the number 123456789.

smsread¶

Console SMS MQTT

Enables writing out received SMSs on the console.

Examples:

smsread=1 - enables function.
smsread=0 - disables function.

inpread¶

Console SMS MQTT

Reads values from sensors.

Sample response:

inpread=0,2,1709,4095,1744,2395,450,0,0,34,64936,64936,-1,-2,-600,-600,-600,-600,-600,-600,-600,-600,0,0,115,-600,-520,1,1,0,0,0,0,0,0,0,0,0,0,0,0

Response content:

adc[0],adc[1],adc[2],adc[3],adc[4],VIN,VBAT,INP1A,INP2A,TEMP,T1,H1,HX711,DIFF,DS1,DS2,DS3,DS4,DS5,DS6,DS7,DS8,inpd1i_licznik,inpd2i_licznik,uptime,P1,signal,INP1D_bb,INP2D_bb,REBOOT_Flaga.bits.b0,REBOOT_Flaga.bits.b1,REBOOT_Flaga.bits.b2,REBOOT_Flaga.bits.b3,REBOOT_Flaga.bits.b4,ON_Flaga.bits.b0,ON_Flaga.bits.b1,ON_Flaga.bits.b2,ON_Flaga.bits.b3,ON_Flaga.bits.b4,MHZ16,OZON

Comments to the response:

REBOOT_Flaga.bits.bx - indicates whether the output is currently in the reboot function (value 1 in progress).
On_Flaga.bits.bx - output state (1 - turned on, 0 - turned off).
MHZ16 - CO2 reading.
OZON - ozone sensor reading.

setread¶

Console SMS MQTT

Reads device settings, other settings are read depending on the parameter.

Examples:

SW 1.16+SW < 1.16

setread=1 - returns 155 items separated by ~: version, name, code, pin, time, call, monitor (a number, whose 20 bits in binary form correspond to readings in events monitoron), apn, httpURL, httpAutoSend, upinpd (INPD1), upinpd (INPD2), mqttPeriod (sending period), mqttHost, mqttPrefix, mqttConfigDone, mqttPort, mqttKeepalive, mqttRead, mqttSelect (low 32 bits of mqttselect), mqttUsername, mqttPassword, mqttBackup, authSMS, smsConfirm, autoRestart, inpa2Sensor, inpa2Calib, remouts, acnumbers (4 consecutive items), actionValue (event threshold, 20 consecutive items), actionHist (event hysteresis, 20 consecutive items), actionOn (action when crossing the threshold up, 20 consecutive items), actionOff (action when crossing the threshold down, 20 consecutive items), actionOutput (output associated with the event, 20 consecutive items), actionDelay (delay vindelay to the event, 20 consecutive items), imei, mqttSelect (high 32 bits of mqttselect).
setread=2 - 40 items separated by ~: textOn, textOff (20 pairs, text for events - when going over or going below the threshold).

setread=1 - returns 154 items separated by ~: version, name, code, pin, time, call, monitor (a number, whose 20 bits in binary form correspond to readings in events monitoron), apn, httpURL, httpAutoSend, upinpd (INPD1), upinpd (INPD2), mqttPeriod (sending period), mqttHost, mqttPrefix, mqttConfigDone, mqttPort, mqttKeepalive, mqttRead, mqttSelect (the number, whose 31 bits in binary form correspond to mqttselect), mqttUsername, mqttPassword, mqttBackup, authSMS, smsConfirm, autoRestart, inpa2Sensor, inpa2Calib, remouts, acnumbers (4 consecutive items), actionValue (event threshold, 20 consecutive items), actionHist (event hysteresis, 20 consecutive items), actionOn (action when crossing the threshold up, 20 consecutive items), actionOff (action when crossing the threshold down, 20 consecutive items), actionOutput (output associated with the event, 20 consecutive items), actionDelay (delay vindelay to the event, 20 consecutive items), imei.
setread=2 - 40 items separated by ~: textOn, textOff (20 pairs, text for events - when going over or going below the threshold).

numread¶

Console SMS MQTT

Reads the numbers authorized for the call function.

Examples:

numread=1 - numbers from positions 1-50, separated by ~.
numread=2 - numbers from positions 51-100, separated by ~.

sleep¶

Added in SW 1.15

Console SMS MQTT

Enables the energy saving function.

Examples:

sleep=0 - 20mA (average power consumption from a 7.4V Li-Po battery) - full functionality, MQTT connection with keepAlive = 60.
sleep=1 - 13mA - full functionality, MQTT connection with keepAlive = 60, compared to sleep=0 the modem is put into a low power state but works normally.
sleep=3 - 5mA - processor paused, no MQTT connection, only receiving calls or SMS with commands.

Attention!

When powered directly (bypassing the converter) from Li-Po 3.7V, the currents are even lower, but with some battery discharge, there is a problem with switching on the relay. In such applications, the relay would have to be replaced with 3.3V.

mqttsend¶

Console SMS MQTT

Sets the period of sending readings via MQTT, selected by mqttselect.

Examples:

mqttsend=300 - sets the period to 300s.

mqttserver¶

Console SMS MQTT

Sets the address of the MQTT server, accepted value is domain or IP address.

Examples:

mqttserver=mqtt.ats.pl

mqttport¶

Console SMS MQTT

Sets the port of the MQTT server.

Examples:

mqttport=1883

tls¶

Added in SW 1.29

Console SMS MQTT

Specifies whether the MQTT connection should use encryption or not. Until version SW 1.29 the use of encryption depended on the value of mqttport - for ports below 8000 the connection was not encrypted.

Examples:

tls=1 - enables encryption support

mqttkeepalive¶

Console SMS MQTT

Sets the KeepAlive parameter for the MQTT connection. Normally it should be the same as mqttsend.

Examples:

mqttkeepalive=300

mqttid¶

Console SMS MQTT

Sets the prefix of MQTT topics - defines on which topics the readings will be sent and on which topic the controller will listen for commands and send responses (mqttid/cmd, mqttid/cmdr).

Examples:

mqttid=prefix/qwe

mqttread¶

Console SMS MQTT

Sets the number of readings to be sent in the MQTT message every mqttsend. By default, it is 1 - a single reading in the message, maximum 12. For a value greater than 1, the message will contain the set number of readings, saved in the format [read1,read2] (measurements are performed every mqttsend/mqttread, and sending every mqttsend).

mqttselect¶

Console SMS MQTT

Selects which readings are to be sent cyclically after the MQTT. The setting is toggled, ie the given items are turned on if they were turned off or turned off if they were turned on.

List of readings:

0: vin_adc
1: vbat_adc
2: inpa1_adc
3: inpa2_adc
4: temp_adc
5: vin
6: vbat
7: inpa1
8: inpa2
9: temp
10: t1
11: h1
12: hx711
13: diff
14: ds1
15: ds2
16: ds3
17: ds4
18: ds5
19: ds6
20: ds7
21: ds8
22: inpd1i
23: inpd2i
24: uptime
25: p1
26: signal
27: inpd1
28: inpd2
29: co2
30: ozon
31: pm1 # added in SW 1.16
32: pm2 # added in SW 1.16
33: pm4 # added in SW 1.16
34: pm10 # added in SW 1.16
35: se1 # added in SW 1.17a
36: se2 # added in SW 1.17a
37: se3 # added in SW 1.17a
38: se4 # added in SW 1.17a
39: se5 # added in SW 1.17a
40: se6 # added in SW 1.17a
41: se7 # added in SW 1.17a
42: se8 # added in SW 1.17a
43: se9 # added in SW 1.17a
44: se10 # added in SW 1.17a

Examples:

mqttselect=1,2,3 - changes the state of the function for items 1, 2 and 3.

mqttuser¶

Console SMS MQTT

Sets the username to authenticate during the MQTT connection.

Examples:

mqttuser=user

mqttpass¶

Console SMS MQTT

Sets the password to authenticate during the MQTT connection.

Examples:

mqttpass=pass

mqtttest¶

Console SMS MQTT

Sends the data selected by mqttselect via MQTT.

mqttbackup¶

Console SMS MQTT

WIP

In the case of out of range, it stores the data to be sent in the memory, so that when the connection is renewed, it sends the collected data in several packets.

Examples:

mqttbackup=1 - activates the function.
mqttbackup=0 - deactivates the function.

authsms¶

Console SMS MQTT

Enables checking if the telephone number from which the SMS came with the command is on the list of trusted numbers (number). When the feature is off (default state), anyone can send a command as long as they know the access code (code) and the phone number of the device.

Examples:

authsms=1 - activates the function.
authsms=0 - deactivates the function.

smsconfirm¶

Console SMS MQTT

Enables sending return SMS after commands. Default is on - value 1.

Possible answers are:

sets ok, set ok - successfully accepted command.
no arguments - lack of required parameters for the command.
wrong arguments - invalid command parameter values.
wrong command - command does not exist.
for read commands, the requested information is provided in the response.

Examples:

smsconfirm=1 - activates SMS confirmation.
smsconfirm=0 - deactivates SMS confirmation.

autorestart¶

Console SMS MQTT

Sets the time until automatic restart of the device in hours 1 to 255. For value 0, the function is inactive.

Examples:

autorestart=24 - sets to restart every 24 hours.
autorestart=0 - deactivates the function.

inpa2sensor¶

Console SMS MQTT

Selects sensor support for INPA2.

Available options:

0: Voltage 0-5V
1: ACS711EX 15A
2: ACS711EX 31A
3: ACS709 75A
4: R=0.1
5: R=0.05
6: R=0.01
7: LA100-P
8: ACS711LC 12.5A
9: ACS711LC 25A
10: ACS711LC 20A
11: WCS1800
12: WCS1800 # Added in 1.22

Examples:

inpa2sensor=1 - selects ACS711EX 15A sensor.

inpa2calib¶

Console SMS MQTT

Sets the value for sensor calibration on INPA2.

Examples:

inpa2calib=20

pminterval¶

Added in SW 1.16

Console SMS MQTT

Sets the time after whuch the SPS30 sensor will wake up and take readings for 20 seconds. For 0, the sensor is working all the time, maximum of 65535 seconds.

Examples:

pminterval=0 - sensor is working all the time.
pminterval=20 - sensor sleeps for 20 seconds, then take measurements for 20 seconds.

mqttconfigdone¶

Console SMS MQTT

Determines whether the MQTT configuration has been performed. When connecting to a broker other than mqtt.ats.pl, set it to 1 and set the MQTT connection parameters with other commands.

Examples:

mqttconfigdone=1 - confirms that the MQTT configuration is done - after restart it will try to connect using mqttserver, etc ..
mqttconfigdone=0 - after restart it will connect to the configuration server mqtt.ats.pl.
mqttconfigdone? - reads the state of the flag.

vindelay¶

Console SMS MQTT

Sets the delay after which the action on the event will take effect if the overrun condition persists. For the value 0, no delay. It is used to eliminate unnecessary notifications when the signal changes only for the time acceptable to us. For example, the temperature dropped below the set value, but only for 30 seconds, and then it returned, if the vindelay time was set to more than 30 seconds, we will not get SMS notification or action on outputs. The first parameter defines the related reading (list of inputs in monitoron).

Examples:

vindelay=1:5 - sets a 5 second action delay for VIN.
vindelay=1:0 - removes action delay for VIN.

vinupout¶

Console SMS MQTT

Selects action to do when crossing the vinset threshold up.

Available actions:

1 - sends an SMS with the content set with the desanalog command.
2 - sets the output (selected with the vinoutset command) as for the reboot command, i.e. it turns on for a specified period of time.
4 - turns on the output (selected with the vinoutset command) as for the on command.
8 - turns the output off (selected with the vinoutset command) as for the off command.
16 - sends the current event value via the MQTT.

To select more than one action, enter the sum of the selected items. For example, for SMS and reboot we enter 3, for SMS and turning output on we enter 5, for SMS and turning output off we enter 9.

The first parameter defines the related reading (list of inputs in monitoron).

Examples:

vinupout=1:1 - sets the SMS action for VIN.

vindownout¶

Console SMS MQTT

Selects action to do when crossing the vinset threshold down. Available actions as in vinupout.

The first parameter defines the related reading (list of inputs in monitoron).

Examples:

vindownout=1:1 - sets the SMS action for VIN.

vinoutset¶

Console SMS MQTT

Select the output that will be subject to the reboot, on, off actions.

Available outputs:

0 - OUT0 relay on the board
1 - OUT1 output 1 on the expander board
2 - OUT2 output 2 on the expander board
3 - OUT3 output 3 on the expander board
4 - OUT4 output 4 on the expander board

The first parameter defines the related reading (list of inputs in monitoron).

Examples:

vinoutset=1:0 - sets OUT0 output for action in events for VIN.

out¶

Console SMS MQTT

Toggles the selected output (turns on if it was turned off, and turned off if it's turned on).

Examples:

out=0 - switches the OUT0 output.

usartsensor¶

Console SMS MQTT

Selects a supported module on the serial port.

Available options:

0 - no module
1 - Danfos EKC202C (modbus)
2 - MHZ16/19 CO2
3 - GMQ125 Ozon
4 - SDM72 (added in SW 1.17a)

modbusid¶

Console SMS MQTT

Sets the ID of the Modbus device connected to the serial port.

modbusread¶

Console SMS MQTT

Reads data from the connected module on Modbus.

coread¶

Console SMS MQTT

Reads the value from the CO2 sensor.

ozonread¶

Console SMS MQTT

Reads the value from the Ozone sensor.

pmread¶

Added in SW 1.16

Console SMS MQTT

Reads the values from PM (particulate matter) sensor.

help¶

Console SMS MQTT

Lists available commands on the console.