API SR-Train

Interaction with SIM Roulette
Terms and definitions
Control commands for SIM Roulette SR-Train
Rows
Modems
SMS
Display
Sound
Remote
Variables
Files
Macro management
Settings
Monitoring
Integrating SIM Roulette into your project

Ways to interact with SIM Roulette

1). Direct command input via the SIM Roulette WEB-interface terminal.

2). Creating lists of commands (Macros) via the SIM Roulette WEB-interface and then executing them by the device.

3). A GET or POST request to SIM Roulette of the form http://XXX.XXX.XXX.XXX/port?data=token||step||command

XXX.XXX.XXX.XXX — SIM Roulette IP address
|| — separator
token — code word set via the aggregator’s WEB-interface
step — sequential command number (step)

command — the command

SIM Roulette returns the response in text form. Example: step#!#result
#!# — separator
step — response to the request with the number (step)
data — the result of executing the command (for most commands 1-success, NULL-failure); depending on the command it can also be a number or text. 0 is always encoded as NULL.

4). SIM Roulette contacting a server (your WEB-site) with a GET request to the address specified in the WEB-interface.
For example, http://site.ru/sr/io.php

SIM Roulette sends GET parameters:
step — response to the request with the number (step)
data — result of executing the command
and receives the next command from the server as text: {data}step#!#command
Important! {data} is the required prefix so that SIM Roulette understands the server returns correct data.

Terms and definitions

SIM Roulette returns responses asynchronously.
Each response contains the command number (step).
The SIM Roulette response buffer is dynamic and may contain results of dozens of commands.
0 is always encoded as NULL.
Most commands return: 1 — success, NULL — failure.

Further in the text:
D — number
W — word
X — numeric or character data
(in parentheses) denotes an optional command parameter

Control commands for SIM Roulette SR-Train

ROWS

SR-Train operates with the concept of rows. The contact groups of the modems are divided into 2 rows (A, B). Each row contains 8 SIM cards. The rows of contact groups are separated by 2 empty rows. Another 2 empty rows separate a consist of 2 SR-Train units.

row>calc — counting the number of rows on the existing path (after counting the device will return to row zero and be ready to work)
example: row>calc response: 20number of rows
Note: you can start counting the number of rows by pressing the multifunction button. Do this every time after manually changing the position of the aggregator!

row:D — move to the specified row
D — parameter:

row>shift:D — move by a relative number of rows
D — parameter:

sensor>set:W — carriage shift calibration when moving to another row
W — parameter:

MODEMS

modem>connect — connecting contacts to the SIM cards
example: modem>connect response: 1done 0error
Note: does not work until a row is selected. When connected, a corresponding icon is displayed in the status line on the device screen and in the WEB-interface.
Important! Always visually check whether the contacts are disconnected (raised) during manual interaction with the device. If needed, press the multifunction button to quickly raise the contacts.

modem>disconnect — disconnecting contacts from the SIM card
example: modem>disconnect response: 1always
Note: happens automatically during any mechanical operations of the device

modem>on — turning on the modems
example: modem>on response: 1always
The modems turn on in groups of 4. The delay between turning on modem groups is adjusted with the modem>set:delay command.
Note: when the modem is on, a lightning icon is displayed in the status line on the device screen and in the WEB-interface

modem>on[D] — turning on a range of modems
example: modem>on[1] response: 1always
Group 1: modems 1–4, group 2: 5–8, group 3: 9–12, group 4: 13–16.

modem>off — turning off the modems
example: modem>off response: 1always
Note: happens automatically during any mechanical operations of the device

modem>off[D] — turning off a range of modems
example: modem>off[4] response: 1always
Group 1: modems 1–4, group 2: 5–8, group 3: 9–12, group 4: 13–16.

modem>status[:W] — getting the modems’ status
example: modem>status response: 1power on, contacts connected 0power off or contacts not connected
W — optional parameter:

modem>select:D — select a modem to interact with (1–16)
example: modem>select:3 response: 3selection confirmed 0invalid modem number

modem>set:delay — delay (in milliseconds) between turning on modem groups / modem>set:delay=D — set the delay
examples: modem>set:delay response: 500current delay
modem>set:delay=1000 response: 1000set delay

modem>set:step — number of drive steps of the contact group needed to raise/lower the contacts / modem>set:step=D — set the number of steps
examples: modem>set:step response: 1900current number of steps
modem>set:step=2000 response: 2000set number of steps

modem>set:rate — port speed for data exchange with the modems / modem>set:rate=D — set bitrate
examples: modem>set:rate response: 115200current bitrate
modem>set:rate=57600 response: 57600set bitrate

modem>set:mode — modem operation mode pdu/txt / modem>set:mode=pdu — set the mode
examples: modem>set:mode response: pducurrent mode
modem>set:rate=txt response: txtset mode
Note: information about the current modem mode is needed by the aggregator to process some commands that interact with the modems

modem>send:AT… — send a command to the modem (thus standard AT-commands are sent to the modem)
example: modem>send:ATD+79001234567; response: 1always
Note: all commands beginning with the AT prefix are forwarded by the aggregator to the current modem and the modem>send: construct is not required.
Note: the current modem’s responses arrive asynchronously with Step 0

modem>sms:D — batch retrieval of all SMS from all 16 SIM cards
D — 0-select all SMS, 1-only unread, 2-read, 3-unsent, 4-sent
example: modem>sms:0 response:2## 30,0,"MTS",83
[SMS text]#3#5##E#3#2 — modem number, ## — separator, 30 — SIM card memory cell number, 0 — SMS unread, "MTS" — sender, 83 — message length, #3# — separator between modem reports, 5 — modem number, ## — separator ...

modem>pack:W##M##D — batch execution of a command by all or selected modems
W — AT command
M — modems that must execute the command (1;2;3;4;5;6;7;8;9;10;11;12;13;14;15;16 or all)
D — 1-wait for the response and return it, 0-only send the command for execution and do not wait for modem responses
example: modem>pack:AT+COPS?##all##1 response:1##AT+COPS?
+COPS: 0,0,"Bee Line GSM"
OK
#1#2##AT+COPS?
+COPS: 0,0,"MTS"
OK
#1#3##AT+COPS?
+COPS: 0,0,"TELE2"
OK
#1#4##AT+COPS?
+COPS: 0,0,"ROSTELECOM"
OK
#1#5##AT+COPS?
+COPS: 0,0,"MEGAFON"
OK
#1#6##AT+COPS?
+COPS: 0,0,"Bee Line GSM"
OK
#1#7##AT+COPS?
+COPS: 0,0,"MTS"
OK
#1#8##AT+COPS?
+COPS: 0,0,"TELE2"
OK
#1#9##AT+COPS?
+COPS: 0,0,"ROSTELECOM"
OK
#1#10##AT+COPS?
+COPS: 0,0,"MEGAFON"
OK
#1#11##AT+COPS?
+COPS: 0,0,"Bee Line GSM"
OK
#1#12##AT+COPS?
+COPS: 0,0,"MTS"
OK
#1#13##AT+COPS?
+COPS: 0,0,"TELE2"
OK
#1#14##AT+COPS?
+COPS: 0,0,"ROSTELECOM"
OK
#1#15##AT+COPS?
+COPS: 0,0,"MEGAFON"
OK
#1#16##AT+COPS?
+COPS: 0,0,"Bee Line GSM"
OK
#1##1# — separator

modem>download:URL;FILE[;SIZE] — download a file from a WEB-site and upload it into the memory of the current modem new!
example: modem>download:simroulette.com/download/voice.amr;C:\User\voice.amr; response: 1done 0error

SMS

sms>discover — check for SMS on the SIM card
example: sms>discover response: 1present 0absent

sms>read — copy one SMS (single or concatenated) into the buffer and delete it from the SIM card
example: sms>read response: 1SMS copied 0no SMS

sms>send:X;W — send an SMS
X — subscriber number
W — SMS text (Latin/Russian characters are recognized automatically)
example: sms>send:+79001234567;SMS text response: 1SMS sent 0command syntax error
Note: the command allows sending single-part SMS

sms>send>buffer — send an SMS from the buffer (number;text)
example: sms>send>buffer response: 1SMS sent 0syntax error in buffer

BUFFER

The device’s text buffer is a powerful tool for analyzing input data and forming output data and commands.

buffer>clear — clear the buffer
example: buffer>clear response: 1always

buffer>view — output the buffer contents to the output stream; to build tables you can use bbcode: [table][tr][th][thc[thr][td][tdc][tdr]
example: buffer>view response: ...buffer contents 0buffer empty

buffer>raw — output the buffer contents to the output stream without bbcode processing
example: buffer>raw response: ...buffer contents 0buffer empty

buffer>display — display the buffer contents on the device screen (depending on the amount of data, the device will set the font size and, if needed, pagination)
example: buffer>display response: 1always

buffer>write=W — write new data into the buffer
example: buffer>write=Value A: {a} response: 1always
Important! To substitute a variable value use the constructs {a}, {b}, etc.; to insert a character use {32}, {147}, etc.

buffer>prefix=W — input data that will prepend the current text
example: buffer>write=Start of line{32} response: 1always
Important! To substitute a variable value use the constructs {a}, {b}, etc.; to insert a character use {32}, {147}, etc.

buffer>postfix=W — input data that will append to the current text
example: buffer>write= end of line response: 1always
Important! To substitute a variable value use the constructs {a}, {b}, etc.; to insert a character use {32}, {147}, etc.

buffer>push — save the buffer contents to the stack (device memory)
example: buffer>push response: 1buffer has data 0buffer empty

buffer>pop — restore the buffer contents from the stack
example: buffer>pop response: 1buffer has data 0buffer empty

buffer>swap — swap the buffer contents with the saved copy from the stack
example: buffer>swap response: 1buffer has data 0buffer empty

buffer>merge[=W] — merge the buffer and the saved copy from the stack (the result remains in the buffer)
W — optional parameter; text that will be added between the merged parts
example: buffer>merge={13}{10} response: 1always
Important! To substitute a variable value use the constructs {a}, {b}, etc.; to insert a character use {32}, {147}, etc.

buffer>ussd — copy into the buffer the last USSD response received by the modem (it is stored in a separate USSD stream)
example: buffer>ussd response: 1buffer has data 0buffer empty

buffer>ussd>clear — clear the USSD stream
example: buffer>ussd response: 1always

buffer>time — append the current time (HH:MM) to the buffer
example: buffer>time response: 1always

buffer>date — append the current date (DD.MM.YYYY) to the buffer
example: buffer>date response: 1always

buffer>timestamp — write the internal timestamp to the buffer (in seconds since 01.01.2000)
example: buffer>timestamp response: 1always

buffer>fs>save>file:W — save the buffer contents to a file
example: buffer>fs>save>file:/buffer.txt response: 1done 0error

buffer>fs>write>file:W — append the buffer contents to a file
example: buffer>fs>write>file:/buffer.txt response: 1done 0error

buffer>fs>load>file:W[;D] — read the contents of a file into the buffer
D — optional parameter; read not the whole file but only the specified line
example: buffer>fs>load>file:/buffer.txt;3 response: 1buffer has data 0buffer empty

buffer>sim>save>phone — write the buffer contents into the first phonebook cell named "SR" of the current SIM card
example: buffer>sim>save>phone response: 1done 0error

buffer>sim>load>phone — read into the buffer the number from the first phonebook cell named "SR" of the current SIM card
example: buffer>sim>load>phone response: 1buffer has data 0buffer empty

buffer>modem:grab=D — enable (1) / disable (0) capturing modem responses into the buffer
examples: buffer>modem:grab=1 response: 1modem response capture enabled
buffer>modem:grab=0 response: 0modem response capture disabled

buffer>answer:grab=D — enable (1) / disable (0) capturing device responses into the buffer
examples: buffer>answer:grab=1 response: 1device response capture enabled
buffer>answer:grab=0 response: 0device response capture disabled

buffer>find:W — search the buffer for a character sequence and replace the buffer contents with the found fragment
W — search string:
* — matches any number of arbitrary characters, example: buffer>find:balance* — if the buffer line contains the word "balance", the buffer will keep the text from the word "balance" to the end of the line, response: 1match found 0no matches
[dD] — search for a number with the specified (D) number of digits, example: buffer>find:[d10] response: 110-digit number found 0nothing found — if a number is found, only it remains in the buffer
[sD] — select the specified (D) number of characters from the start of the line or (-D) from the end (Russian characters take 2 bytes), example: buffer>find:[s10] — only the first 10 characters remain in the buffer, response: 1done 0not done

buffer>test:W — check for a character sequence in the buffer
W — search string:
* — matches any number of arbitrary characters, example: buffer>test:balance* response: 1match found 0no matches
[dD] — check for a number with the specified (D) number of digits, example: buffer>test:[d10] response: 110-digit number found 0nothing found
[sD] — check that the specified (D) number of characters exists from the start of the line or (-D) from the end (Russian characters take 2 bytes), example: buffer>cut:[s10] — the buffer will contain only the first 10 characters, response: 1the specified number of characters is present 0the specified number of characters not found

buffer>cut:W — search the buffer for a character sequence and remove the found fragment from the buffer contents
W — search string:
* — matches any number of arbitrary characters, example: buffer>cut:rub.* — if the buffer line contains the word "rub." it and everything after it will be removed, response: 1match found and cut out 0no matches
[dD] — search for a number with the specified (D) number of digits, example: buffer>cut:[d10] response: 110-digit number found and cut 0nothing found — if a number is found, it is cut out
[sD] — delete the specified (D) number of characters from the start of the line or (-D) from the end (Russian characters take 2 bytes), example: buffer>cut:[s10] — the first 10 characters will be removed from the buffer, response: 1the specified number of characters removed 0the specified number of characters not found

DISPLAY

display>clear — clear the screen
example: display>clear response: 1always

display=W — output text and special characters to the screen
W — parameters separated by "::":

examples:
display=10::C::64::30::Text|16::C::64::45::More text
display=10::C::64::35::{English text~Русский текст}! — the corresponding option will be used depending on the selected language
response: 1always

display>com:W — enable/disable screen inversion
W — parameter:

SOUND

sound:beep — short beep
example: sound:beep response: 1always

sound:error — long tone
example: sound:beep response: 1always

REMOTE

key>discover — check if control from the remote is possible (in SR Nano remote/internet control is mutually exclusive; to activate the remote at power-on you must press any button on the remote)
example: key>discover response: 1control possible 0control not possible

key — remote polling (the response will be 1 if any button was pressed; the pressed key name is placed into the buffer)
example: key response: 1button pressed 0button not pressed
possible buffer values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, menu, ok, up, down, left, right, star, hash

VARIABLES

var>W[=D|+D|-D|*D|\D|==D|<D|>D] — working with a variable
W — name of a numeric variable (26 variables available from a to z)

W — name of a text variable (3 variables available: str1, str2, str3)

Important! To insert a variable value into the buffer use the constructs {a}, {b} ... {z}.

FILES

The file system of all SIM Roulette aggregators uses the controller’s internal FLASH memory. The available space, depending on the model, is from 1.5 to 2.5 megabytes.
In some SR Nano configurations, an external microSD memory card may additionally be used.

fs>space:W — view memory status information
W — parameter:

example: fs>space:free response: 100000free size in bytes

fs>list:W — view folder contents
W — folder name
example: fs>list:/ response: ❰ FILE LIST ❱ 0error

fs>view:W — view a file
W — file name
example: fs>view:/terminal.dat response: ❱❱ SWITCHING TO VIEW MODE 0error

fs>edit:W — edit a file
W — file name
example: fs>edit:/terminal.dat response: ❱❱ SWITCHING TO EDITOR 0error

fs>remove:W — delete a file
W — file name
example: fs>remove:/test/file.txt response: 1done 0error

fs>rename:W — rename a file
W — current path and file name _ new path and file name
example: fs>rename:/terminal.dat /test/terminal.dat response: 1done 0error

fs>copy:W — copy a file
W — source file name _ destination file name
example: fs>copy:/terminal.dat /test/terminal.dat response: 1done 0error

fs>download:W — download a file from a WEB-site
W — site address; path and file name in the aggregator’s file system
example: fs>download:simroulette.com/download/test /test/test response: 1done 0error

fs>upload:W — upload a file to a WEB-site
W — site address; path and file name in the aggregator’s file system
example: fs>upload:simroulette.com/upload/test /test/test response: 1done 0error
Important! To implement file reception on your WEB-server, you can use a ready PHP script.

MACRO MANAGEMENT

macro:W (m:W) — run a macro with the specified name from the /m folder (variables are allowed)
examples:
macro:filename response: ❱❱ EXECUTING MACRO 0error
m:filename response: ❱❱ EXECUTING MACRO 0error
macro:file_{a} response: ❱❱ EXECUTING MACRO 0error
Note: macros can be edited and run in the Macros section of the SR-Nano WEB-interface; you can also track execution progress there.

macro>stop (m>stop) — stop executing the current macro

SETTINGS

answer — allow (answer=1) or disallow (answer=0) printing command responses to the output stream
example: answer=1 response: 1confirmation of the entered data

answer>clear — clear the response buffer
example: answer>clear response: 1always

busy_enable — allow (busy_enable=1) or disallow (busy_enable=0) the device to ignore network requests while it performs mechanical actions; enter busy_enable to view the current setting
example: busy_enable response: 1allowed 0disallowed

carrier_time — idle time (in seconds) between SIM Roulette commands; when the timer ends SIM Roulette reconnects to the network / carrier_time=D — set the time
example: carrier_time=60 response: 60confirmation of the entered data

server_url — server URL / server_url=W — set the URL
example: server_url=link.simroulette.com/?token=12345 response: link.simroulette.com/?token=12345confirmation of the entered data

server_fr — server polling frequency / server_fr=D — set the frequency
example: 1000 response: 1000confirmation of the entered data

sms_check — interval (in seconds) for checking incoming SMS on the active SIM card / sms_check=D — set the time (0 — SMS presence is not checked)
example: sms_check=30 response: 30confirmation of the entered data

pdu — enable (pdu=1) or disable (pdu=0) auto-conversion from PDU for incoming SMS and USSD responses; enter pdu to view the current setting
example: pdu response: 1enabled 0disabled

status — allow (status=1) or disallow (status=0) saving the current statuses of contact connection and modem power (after power-on the aggregator reads the saved status and restores the picture at the moment of power-off or reboot)
example: status response: 1status is saved 0status is NOT saved

debug — allow (debug=1) or disallow (debug=0) displaying debug information (e.g., macro execution progress) on the device screen; enter debug to view the current setting
example: debug response: 1enabled 0disabled

version> — current software version
example: version response: 1.01current version

save — save settings to the configuration file (without saving, settings remain active only until the device is rebooted)
example: save response: 1 always

MONITORING

request — a command to retrieve a response (the result of previous commands) from the device (the command does not perform any actions)

email>send:[email];[topic] — send an email
example: email:user@mail.ru;New information from SIM Roulette response: 1email sent 0invalid settings

restart — soft reset of the device
example: restart response: 1 ❱❱ DEVICE REBOOT

Integrating SIM Roulette into your project

We hope the information above will help you integrate SIM Roulette into your project without problems.
To simplify the task, we recommend using the WEB panel SR-Navigator and the API to interact with your software.
And of course, you can always use the services of our programmers.