Skip to content

AT Scripting Generic Macros (m‐center specific)

Jump to bottom
Iftikhar Aziz edited this page Jul 19, 2024 · 3 revisions
  • backslash (\) is used to write (") inside a string. e.g. str"str
  • If ";" is used at the end of AT command, then it is recommended to use a double semicolon ";;" e.g. in SENDAT() macro.
  • If the main is defined, make sure to call all macros inside main or a function. Only variables can be called outside the scope of main functions. If a macro is called outside the main or any function script will not run and return an error.
  • In the case of an absolute path, the complete file path (with double \\ ) shall be entered e.g., "C:\\test_dir\\testfile.bin".

1. Send Macros

SENDAT

string SENDAT(string cmd, int timeout, string resp, bool exactMatchWithResp = false);

This macro send AT command.
This macro is useful when variable parameters are used in AT command or a specific type of response can be required. For instance, to send some data to the modem which does not start from the "AT" keyword. Empty Quotes ('') could be used as a wild-card response to get any string till \r\n that is received in response to AT command.

PARAMETERS
cmd: string AT command or data to send.
timeout: int Timeout value to return the macro response. The default timeout is 20ms and can only be a multiple of 10, while the timeout=0 is set to infinite i.e 2,147,483,647 (max int range). Minimum=20ms Maximum=max integer Limit (2,147,483,647)
resp: string Expected response to wait as a reply.
exactMatchWithResp: bool The parameter 'exactMatchWithResp' can be used to search for the exact response to match. (false by default).
true - exact response to match in AT command reply.
false - no exact response to match in AT command reply.

RETURN VALUE
Return type: string

EXAMPLE

string resp = SENDAT("ATD+123456789;", 5000, "OK");
ECHO("RESPONSE=" + resp);

OUTPUT

Script Started
ATD+03214091919;
OK
AT script: RESPONSE=OK
Script Stopped

EXAMPLE

string resp = SENDAT("AT+CSQ", 5000, "OK",true);
ECHO("RESPONSE=" + resp);

OUTPUT

Script Started
AT+CSQ
+CSQ: 23,1
OK
AT script: RESPONSE=+CSQ: 23,1
OK
Script Stopped

EXAMPLE

SENDAT("AT+CGDCONT?",1000,"OK");
string apn_StringByUser = "warid";
ECHO("apn_StringByUser=" + apn_StringByUser);
string cid_StringByUser = "1";
ECHO("cid_StringByUser=" + cid_StringByUser);
SENDAT("AT+CGDCONT=" + cid_StringByUser + ",\"IP\"," + "\"" + apn_StringByUser + "\"",1000,"OK");
SENDAT("AT+CGDCONT?",1000,"OK");

OUTPUT

Script Started
AT+CGDCONT?
+CGDCONT: 1,"IP","<APN>","",0,0,0,0,0,0
+CGDCONT: 4,"IP","internet.mnc006.mcc410.gprs","100.97.114.182",0,0,0,0,0,0
OK
AT script: apn_StringByUser=warid
AT script: cid_StringByUser=1
AT+CGDCONT=1,"IP","warid"
OK
AT+CGDCONT?
+CGDCONT: 1,"IP","warid","",0,0,0,0,0,0
+CGDCONT: 4,"IP","internet.mnc006.mcc410.gprs","100.97.114.182",0,0,0,0,0,0
OK
Script Stopped

SUPPORTED BY
m-center v02.01.00 (and onward)

SENDHEX

bool SENDHEX(string inParam1);

This macro sends HEX data to the modem. Returns the response in bool.

PARAMETERS
inParam1: string hex string having 2-digits and separated with space.

RETURN VALUE
Return type: bool

EXAMPLE

bool resp = SENDHEX("7E 4B 25 03 00 92 3A 7E");
ECHO("RESPONSE=" + resp);

OUTPUT

Script Started
AT script: RESPONSE=true
Script Stopped

SUPPORTED BY
m-center v02.04.00 (and onward)

SENDTEXT

bool SENDTEXT(string inParam1);

This macro sends raw TEXT to the modem. The returns value is bool.

PARAMETERS
inParam1: string

RETURN VALUE
Return type: bool

EXAMPLE
bool resp = SENDTEXT("Hello World");

SUPPORTED BY
m-center v02.04.00 (and onward)

SENDFILE

bool SENDFILE(string inParam1);

This macro sends a file to the modem through a direct link.

PARAMETERS
inParam1: string File path in the local storage.

Note: If the path is relative e.g. "testfile.bin" the file should be present where the running script is present. In the case of an absolute path, the complete file path (with \\) should be entered e.g. "C:\\test_dir\\testfile.bin".

RETURN VALUE
Return type: bool True in case of success or False in case of some error.

EXAMPLE

string send_file_name = "testfile.bin";
string send_file_cmd = "AT+UDWNFILE=\"testfile.bin\",65378";

void main()
{
	ECHO("Sending AT Command");
	SENDAT(send_file_cmd,100,"OK");
	
	ECHO("Sending File");
	
	if(SENDFILE(send_file_name)) //Relative Path
	{
		ECHO("SUCCESS: File stored to the modem!");
	}
	else
	{
		ECHO("ERROR: Cannot store File!");
	}
 
}

OR

string file_path = "C:\\test_dir\\";  
string file_name = "testfile.bin";
string send_file_cmd = "AT+UDWNFILE=\"testfile.bin\",65378";

void main()
{
	ECHO("Sending AT Command");
	SENDAT(send_file_cmd,100,"OK");
	
	ECHO("Sending File");
	
	if(SENDFILE(file_path+file_name)) //Absolute Path
	{
		ECHO("SUCCESS: File stored to the modem!");
	}
	else
	{
		ECHO("ERROR: Cannot store File!");
	}
 
}

OUTPUT

Script Started
AT script: Sending AT Command
AT+UDWNFILE="testfile.bin",65378

>
AT script: Sending File
AT script: Bytes Transferred: 4096/65378 (6%)
AT script: Bytes Transferred: 8192/65378 (12%)
AT script: Bytes Transferred: 12288/65378 (18%)
AT script: Bytes Transferred: 16384/65378 (25%)
AT script: Bytes Transferred: 20480/65378 (31%)
AT script: Bytes Transferred: 24576/65378 (37%)
AT script: Bytes Transferred: 28672/65378 (43%)
AT script: Bytes Transferred: 32768/65378 (50%)
AT script: Bytes Transferred: 36864/65378 (56%)
AT script: Bytes Transferred: 40960/65378 (62%)
AT script: Bytes Transferred: 45056/65378 (68%)
AT script: Bytes Transferred: 49152/65378 (75%)
AT script: Bytes Transferred: 53248/65378 (81%)
AT script: Bytes Transferred: 57344/65378 (87%)
AT script: Bytes Transferred: 61440/65378 (93%)
AT script: Bytes Transferred: 65378/65378 (100%)
AT script: SUCCESS: File stored to the modem!
Script Stopped

OK

SUPPORTED BY
m-center v02.08.00 (and onward)

2. Flow control Macros (SET/GET)

SETCOMRTS

void SETCOMRTS(bool &in);

Sets the RTS (request-to-send) flow control.

PARAMETERS
in: bool true=low | false=high

RETURN VALUE
Return type: void

SUPPORTED BY
m-center v02.05.00 (and onward)

SETCOMDTR

void SETCOMDTR(bool &in);

Sets the DTR (data-terminal-ready) flow control.

PARAMETERS
in: bool true=low | false=high

RETURN VALUE
Return type: void

SUPPORTED BY
m-center v02.05.00 (and onward)

GETCOMCTS

bool GETCOMCTS(void);

Gets the CTS (clear-to-send) status of the modem.

PARAMETERS
void

RETURN VALUE
Return type: bool true=low | false=high

SUPPORTED BY
m-center v02.05.00 (and onward)

GETCOMDSR

bool GETCOMDSR(void);

Gets the DSR (data-set-ready) status of the modem.

PARAMETERS
void

RETURN VALUE
Return type: bool true=low | false=high

SUPPORTED BY
m-center v02.05.00 (and onward)

GETCOMRI

bool GETCOMRI(void);

Gets the RI (ring indicator) status of the modem.

PARAMETERS
void

RETURN VALUE
Return type: bool true=low | false=high

SUPPORTED BY
m-center v02.05.00 (and onward)

GETCOMDCD

bool GETCOMDCD(void);

Gets the RLSD (receive-line-signal-detect) status of the modem.

PARAMETERS
void

RETURN VALUE
Return type: bool true=low | false=high

SUPPORTED BY
m-center v02.05.00 (and onward)

3. Utility Macros

SWAPENDIAN

string SWAPENDIAN(string inParam1);
uint16 SWAPENDIAN(uint16 inParam2);
uint32 SWAPENDIAN(uint32 inParam3);

This macro swaps little-endian to big-endian and big-endian to little-endian, respectively. The macro can be used with either string, unsigned short integer, or unsigned long integer as an input argument and returns the response according to the input argument.

PARAMETERS
inParam1: string
inParam2: uint16
inParam3: uint32

RETURN VALUE
Return Type: string OR
Return Type: uint16 OR
Return Type: uint32

EXAMPLE
The return value would be a string if the input argument is a string. In case of the given string is not correctly formatted or the length of the given string is not an even number, the following warning message will be displayed.
"SwapEndian: WARNING: Ignoring last incomplete byte"

string inputstr ="12345678";
ECHO('inputstr=' + inputstr);
string outputstr = SWAPENDIAN(inputstr);
ECHO('outputstr=' + outputstr);

OUTPUT

Script Started
AT script: inputstr=12345678
AT script: outputstr=78563412
Script Stopped

EXAMPLE
If the input argument is an unsigned short integer, it will return the value as an unsigned short integer.

uint16 input = 255;
ECHO(formatUInt(input, 'H',4));
uint16 output = SWAPENDIAN(input);
ECHO(formatUInt(output, 'H',4));

OUTPUT

Script Started
AT script:   FF
AT script: FF00
Script Stopped

EXAMPLE
If the input argument is an unsigned long integer, it will return the value as an unsigned long integer.

uint32 input = 65535;
ECHO(formatUInt(input, 'H',8));
uint32 output = SWAPENDIAN(input);
ECHO(formatUInt(output, 'H',8));

OUTPUT

Script Started
AT script:     FFFF
AT script: FFFF0000
Script Stopped

SUPPORTED BY
m-center v02.04.00 (and onward) string parameter only
m-center v02.08.00 (and onward) string|uint16|uint32

TIMEELAPSED

int TIMEELAPSED(void);

This macro returns the time elapsed since the start of the AT script in milliseconds.

PARAMETERS
void

RETURN VALUE
Return type: int Time elapsed since the start of the AT script in milliseconds

EXAMPLE

SENDAT("AT", 1000, "OK");
ECHO TIMEELAPSED();
PAUSE(10);
SENDAT("AT+CGMI", 1000, "OK");
ECHO TIMEELAPSED();
PAUSE(20);

OUTPUT

Script Started
AT
OK
AT script: 79
AT script: Starting Pause: <10> msec
AT+CGMI
u-blox
OK
AT script: 204
AT script: Starting Pause: <20> msec
Script Stopped

SUPPORTED BY
m-center v02.09.00 (and onward)

STOP

void STOP(string msg);

This macro stops the script after printing the "msg" string on the AT Terminal.

PARAMETERS
msg: string

RETURN VALUE
Return type: void

SUPPORTED BY
m-center v02.04.00 (and onward)

FIND

int FIND(string &str, string &search);

This macro searches in the string "str" for the first occurrence of the sequence specified by its argument "search". Returns an integer index of the first occurrence of the search pattern, -1 if the search pattern does not exist.

PARAMETERS
str: string
search: string

RETURN VALUE
Return type: int

EXAMPLE

string str = "0123456789";
ECHO "str = " + str;
ECHO "FIND(str,\"0\") = " + FIND(str,"0");
ECHO "FIND(str,\"1\") = " + FIND(str,"1");
ECHO "FIND(str,\"2\") = " + FIND(str,"2");
ECHO "FIND(str,\"3\") = " + FIND(str,"3");
ECHO "FIND(str,\"4\") = " + FIND(str,"4");
ECHO "FIND(str,\"5\") = " + FIND(str,"5");
ECHO "FIND(str,\"6\") = " + FIND(str,"6");
ECHO "FIND(str,\"7\") = " + FIND(str,"7");
ECHO "FIND(str,\"8\") = " + FIND(str,"8");
ECHO "FIND(str,\"9\") = " + FIND(str,"9");
ECHO "FIND(str,\"123\") = " + FIND(str,"123");
ECHO "FIND(str,\"456789\") = " + FIND(str,"456789");
ECHO "FIND(str,\"0123456789\") = " + FIND(str,"0123456789");
ECHO "FIND(str,\"654\") = " + FIND(str,"654");

OUTPUT

Script Started
AT script: str = 0123456789
AT script: FIND(str,"0") = 0
AT script: FIND(str,"1") = 1
AT script: FIND(str,"2") = 2
AT script: FIND(str,"3") = 3
AT script: FIND(str,"4") = 4
AT script: FIND(str,"5") = 5
AT script: FIND(str,"6") = 6
AT script: FIND(str,"7") = 7
AT script: FIND(str,"8") = 8
AT script: FIND(str,"9") = 9
AT script: FIND(str,"123") = 1
AT script: FIND(str,"456789") = 4
AT script: FIND(str,"0123456789") = 0
AT script: FIND(str,"654") = -1
Script Stopped

SUPPORTED BY.
m-center v02.04.00 (and onward)

WAIT

Prototype 1: string WAIT(string str1, int timeout, bool exactline = false);
Prototype 2: string WAIT(string str1, string str2, int timeout, bool exactline = false);

This command waits until a specified string "str1" is received from the modem or a timeout (milliseconds) has occurred. Returns the response containing "str1" or an empty string in case of timeout. The parameter 'exactline' can return only the str1 containing the response specified (false by default).

This command can also be used with two string parameters "str1" and "str2". Returns the response if any of the strings are received mentioned in str1 and str2. This command is useful for waiting until a given URC is received or an ERROR message is received.

PARAMETERS Prototype 1
str1: string string value given by the user to wait for by the macro.
timeout: int Timeout value to return the macro response. The default timeout is 20ms and can only be a multiple of 10, while the timeout=0 is set to infinite i.e 2,147,483,647 (max int range). Minimum=20ms Maximum=max integer Limit (2,147,483,647)
exactline : bool Default value is false.

PARAMETERS Prototype 2
str1: string string value given by the user to wait for by the macro.
str2: string string value given by the user to wait for by the macro.
timeout: int Timeout value to return the macro response. The default timeout is 20ms and can only be a multiple of 10, while the timeout=0 is set to infinite i.e. 2,147,483,647 (max int range). Minimum=20ms Maximum=max integer Limit (2,147,483,647)
exactline : bool Default value is false.

RETURN VALUE
Return type: string

EXAMPLE

string resp = WAIT("OK", 10000);
string resp = WAIT("OK", 1000, true);

EXAMPLE

string resp = WAIT("OK", "ERROR", 1000);
string resp = WAIT("OK", "ERROR", 1000, true);

SUPPORTED BY
m-center v02.04.00 (and onward)

PAUSE

void PAUSE(int timeout);

This command inserts a delay between AT script commands, the keyword "PAUSE" has to be used along with the desired delay in milliseconds i.e., PAUSE + space + numerical value expressed in milliseconds.

PARAMETERS
timeout: int

RETURN VALUE
Return type: void

EXAMPLE

PAUSE 1000;
PAUSE(1000);

SUPPORTED BY
m-center v02.04.00 (and onward)

ECHO

void ECHO(string echoString);

This macro prints on AT Terminal, the keyword "ECHO" can be used with the desired print string i.e. ECHO +space +string value in double quotation marks. The maximum supported length for the string is fixed to 512 bytes.

PARAMETERS
echoString: string

RETURN VALUE
Return type: void

EXAMPLE

ECHO "To be printed";
ECHO("To be printed");

SUPPORTED BY
m-center v02.01.00 (and onward)

STRING2HEX

string STRING2HEX(string str);

This command converts string data to its hexadecimal format and returns the value as a string.

PARAMETERS
str: string

RETURN VALUE
Return type: string

EXAMPLE

ECHO(STRING2HEX("AT"));

OUTPUT

4154

SUPPORTED BY
m-center v02.04.00 (and onward)

HEX2STRING

string HEX2STRING(string str);

This command converts hexadecimal string data to its string format.

PARAMETERS
str: string

RETURN VALUE
Return type: string

EAMPLE

ECHO(HEX2STRING("4154"));

OUTPUT

AT

SUPPORTED BY
m-center v02.04.00 (and onward)

SET_RXTX_TERMINATION

bool SET_RXTX_TERMINATION(string strTerminationCh);

This macro sets the termination characters for TX and RX.

PARAMETERS
strTerminationCh: string
"CR" : TX=CR | RX=CR
"LF" : TX=LF | RX=LF
"CRLF" : TX=CRLF | RX=CRLF
"DEFAULT": TX=CR | RX=CRLF

RETURN VALUE
Return type: bool

EXAMPLE

SET_RXTX_TERMINATION("CR");
SET_RXTX_TERMINATION("LF");
SET_RXTX_TERMINATION("CRLF");
SET_RXTX_TERMINATION("DEFAULT");

SUPPORTED BY
m-center v02.08.00 (and onward)

EXEC

bool EXEC(string appToExecute, string par = "", string oper = "open", string dir = "", int show = 0)

This macro executes an external application. It has the following parameters. In the case of an absolute path, the complete file path (with double \\ ) should be entered e.g. "C:\\test_dir\\testfile.bin".

PARAMETERS
appToExecute: string
par: string [optional] default value empty
oper: string [optional] default value "open"
"edit"
"explore"
"find"
"open"
"print"
"runas"
dir: string [optional] default value empty
show: int [optional] default value 0=SW_HIDE
0 = SW_HIDE,
1 = SW_NORMAL,
2 = SW_SHOWMINIMIZED,
3 = SW_SHOWMAXIMIZED,
4 = SW_SHOWNOACTIVATE,
5 = SW_SHOW,
6 = SW_MINIMIZE,
7 = SW_SHOWMINNOACTIVE,
8 = SW_SHOWNA,
9 = SW_RESTORE,
10 = SW_SHOWDEFAULT,
11 = SW_FORCEMINIMIZE

RETURN VALUE
Return type: bool

EXAMPLE
EXEC("m-center.exe","","open","",5);
EXEC("cmd.exe","","open","",5);
EXEC("m-center.exe","","open","C:\\Program Files (x86)\\u-blox\\m-center",1);

SUPPORTED BY
m-center v02.08.00 (and onward)

RAND

int RAND(int X)

This macro generates a random number from 0 to X. It has the following parameters

PARAMETERS
X: int

RETURN VALUE
Return type: int

EXAMPLE

ECHO(RAND(50));

OUTPUT

19 (value can be any random value ranging from 0 to 50)

EXAMPLE

# below code will generate 5 random numbers value ranging from 0 to 50
for(int i =0; i < 5; i++)
	ECHO(RAND(50));

OUTPUT

19 (value can be any random value ranging from 0 to 50)
38
6
27
41

SUPPORTED BY
m-center v02.08.00 (and onward)

4. User Input Macros

UI_INPUT

string UI_INPUT(string inParam1);

This macro gets text as input. A pop-up is displayed that allows the user to input the required value in the form of a string returned by the macro in the script as a string. The return value can later be converted to any desired type, like an integer inside the script.

PARAMETERS
inParam1: string

RETURN VALUE
Return type: string

EXAMPLE

SENDAT("AT+CGDCONT?",1000,"OK");
string inputAPN_StringByUser = UI_INPUT("Enter value of APN");
ECHO("inputAPN_StringByUser=" + inputAPN_StringByUser);
string inputCID_StringByUser = UI_INPUT("Enter value of CID");
int inputCID_IntByUser = parseInt(inputCID_StringByUser);
ECHO("inputCID_IntByUser=" + inputCID_IntByUser);
SENDAT("AT+CGDCONT=" + inputCID_StringByUser + ",\"IP\"," + "\"" + inputAPN_StringByUser + "\"",1000,"OK");

OUTPUT

Script Started
AT+CGDCONT?
+CGDCONT: 1,"IP","warid","",0,0,0,0
+CGDCONT: 11,"IPV4V6","ims","",0,0,0,0
+CGDCONT: 12,"IPV4V6","sos","",0,0,0,1
OK
AT script: inputAPN_StringByUser=warid
AT script: inputCID_IntByUser=1
AT+CGDCONT=1,"IP","warid"
OK
Script Stopped

SUPPORTED BY
m-center v02.08.00 (and onward)

UI_INFO

bool UI_INFO(string Head, string Body, int Yes_No/Ok);

This macro gets text as input as parameters. A pop-up is displayed that allows the user to perform the desired action, while action is returned by the macro in the script as a bool. The return value can later be used inside the script.

PARAMETERS
Head: string
Body: string
Yes_No/Ok: int

RETURN VALUE
Return type: bool

EXAMPLE

UI_INFO("m-center -Head","m-center -Body This is message body",0);
UI_INFO("m-center -Head","m-center -Body This is message body",1);

OUTPUT

Message boxes are displayed.

SUPPORTED BY
m-center v02.09.00 (and onward)

Clone this wiki locally