API SR-Box/SR-Board

Interaction with SIM Roulette
Terms and definitions
Control commands for SIM Roulette SR-Box
Modem
Audio
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 command lists (Macros) via the SIM Roulette web interface and then executing them on the device.

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

XXX.XXX.XXX.XXX — SIM Roulette IP address
|| — separator
token — passphrase set via the aggregator’s web interface
step — command sequence number (step)

command — the command

SIM Roulette returns the answer as plain text. Example: step#!#result
#!# — separator
step — response to the request with its number (step)
data — command execution result (for most commands 1-success, NULL-failure); depending on the command, this may also be a number or text. 0 is always encoded as NULL.

4). SIM Roulette requests your server (your website) 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 its number (step)
data — command execution result
and receives from the server the next command as text: {data}step#!#command
Important! {data} is the required prefix so that SIM Roulette understands the server returns valid data.

Terms and definitions

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

Hereafter 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-Box

GSM MODEM

modem>on — turn modems on
example: modem>on response: 1always
Modems are powered on in groups of 4. The delay between powering modem groups is configured with modem>set:delay
Note: when the modem is on, a lightning icon appears in the device’s status line and in the web interface.

modem>on[D] — turn on a modem group
example: modem>on[1] response: 1always
Group 1: modems 1–4, Group 2: modems 5–8.

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

modem>off[D] — turn off a modem group
example: modem>off[2] response: 1always
Group 1: modems 1–4, Group 2: modems 5–8.

modem>status — get modem power status
example: modem>status response: 1power on 0power off

modem>select:D — select a modem to interact with (1–8)
example: modem>select:D response: 3confirmation of selected modem number
Note: when modem>set:echo=1 is enabled, while switching to the next modem the previous modem’s responses continue to be received in the background.

modem>set:echo — enable (modem>set:echo=1) or disable (modem>set:echo=0) background modem polling
examples: modem>set:echo=1 response: 1selection confirmed

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

modem>set:rate — port speed for data exchange with 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 operating mode / TXT (modem>set:mode=txt) or PDU (modem>set:mode=pdu)
examples: modem>set:mode response: pducurrent mode
modem>set:mode=txt response: txtset mode
Note: information about the current modem mode is needed by the aggregator for processing certain modem-related commands.

modem>set:auto — modem auto power mode / enabled (modem>set:auto=1) or disabled (modem>set:auto=0)
examples: modem>set:auto response: 1current mode
modem>set:auto=1 response: 1auto power enabled

modem>send:AT… — send a command to the current modem (standard AT commands are passed this way)
example: modem>send:ATD+79001234567; response: 1always
Note: any command starting with the AT prefix is forwarded by the aggregator to the current modem, so the modem>send: prefix is optional.
Note: responses from the current modem arrive asynchronously with Step (step) 0.

modem>sms:D — batch retrieval of all SMS from all 8 SIM cards
D — 0-select all, 1-unread only, 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 memory slot 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 to execute the command (1;2;3;4;5;6;7;8 or all)
D — 1-wait for a response and return it, 0-send the command without waiting 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##1# — separator

AUDIO

audio>[D1]:[D2] — SR-Box-Voice headset switch
D1 — select audio interface 1 (modems 1–4) / 2 (modems 5–8)
D2 — select modem for the chosen interface (1–4)
example: audio>2:4 response: 2:4input confirmed
Modem 8 will be connected to interface 2 (microphone, headphones)

SMS

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

sms>read — copy one SMS (single or concatenated) to 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 — recipient number
W — SMS text (Latin/Cyrillic detected automatically)
example: sms>send:+79001234567;SMS text response: 1SMS sent 0command syntax error
Note: the command sends a 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

sms>clear — delete all SMS from the SIM card
example: sms>clear response: 1always

BUFFER

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

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

buffer>view — output buffer contents to stdout; 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 buffer contents to stdout without bbcode processing
example: buffer>raw response: ...buffer contents 0buffer empty

buffer>display — display buffer contents on the device screen (depending on data size the device adjusts font size and 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 construction {a}, {b}, etc.; to insert a character use {32}, {147}, etc.

buffer>prefix=W — prepend data to the current text
example: buffer>write=Line start{32} response: 1always
Important! To substitute a variable value use the construction {a}, {b}, etc.; to insert a character use {32}, {147}, etc.

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

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

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

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

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

buffer>ussd — copy to the buffer the last modem USSD response (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 to the buffer (HH:MM)
example: buffer>time response: 1always

buffer>date — append the current date to the buffer (DD.MM.YYYY)
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 buffer contents to a file
example: buffer>fs>save>file:/buffer.txt response: 1done 0error

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

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

buffer>sim>save>phone — write buffer contents to SIM phonebook slot 1 with name "SR" (current SIM)
example: buffer>sim>save>phone response: 1done 0error

buffer>sim>load>phone — read into the buffer the number from SIM phonebook slot 1 named "SR" (current SIM)
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 combination; replace buffer contents with the found fragment
W — search string:
* — matches any number of arbitrary characters, example: buffer>find:balance* — if the buffer contains the word "balance", the buffer will keep the text from "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 found, only that number remains in the buffer
[sD] — select the specified (D) number of characters from the start, or (-D) from the end (Cyrillic characters occupy 2 bytes), example: buffer>find:[s10] — only the first 10 characters remain in the buffer, response: 1done 0not done

buffer>test:W — test for a character combination 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 the presence of the specified (D) number of characters from the start, or (-D) from the end (Cyrillic characters occupy 2 bytes), example: buffer>cut:[s10] — the buffer will contain only the first 10 characters, response: 1required number of characters present 0required number of characters not found

buffer>cut:W — search the buffer for a character combination; delete the found fragment from the buffer
W — search string:
* — matches any number of arbitrary characters, example: buffer>cut:rub.* — if the buffer contains the word "rub.", it and everything after it will be deleted, response: 1match found and cut 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 — the number is cut if found
[sD] — delete the specified (D) number of characters from the start, or (-D) from the end (Cyrillic characters occupy 2 bytes), example: buffer>cut:[s10] — the first 10 characters are cut from the buffer, response: 1cut performed 0required number of characters not found

DISPLAY

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

display=W — print text and special characters on 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~Русский текст}! — depending on the selected language, the corresponding option will be used
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:error response: 1always

REMOTE

key>discover — check if remote control is possible (in SR Box, remote/web control are mutually exclusive; to activate the remote after powering on, press any button on the remote)
example: key>discover response: 1control available 0control unavailable

key — poll the remote (the response returns 1 if any button was pressed; the pressed key name is placed into the buffer)
example: key response: 1button pressed 0no button press
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] — work with a variable
W — numeric variable name (26 variables available: a to z)

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

Important! To insert a variable value into the buffer use {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.

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

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

fs>list:W — list directory 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: ❱❱ ENTERING VIEW MODE 0error

fs>edit:W — edit a file
W — file name
example: fs>edit:/terminal.dat response: ❱❱ ENTERING 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 website
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 website
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-made PHP script.

MACRO MANAGEMENT

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

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

SETTINGS

answer — allow (answer=1) or forbid (answer=0) printing command responses to stdout
example: answer=1 response: 1confirmation

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

carrier_time — idle time (seconds) between SIM Roulette commands; after the timer expires, SIM Roulette reconnects to the network / carrier_time=D — set time
example: carrier_time=60 response: 60confirmation

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

server_fr — server polling frequency / server_fr=D — set frequency
example: 1000 response: 1000confirmation

sms_check — interval (seconds) to check for SMS on the active SIM card / sms_check=D — set time (0 — do not check for SMS)
example: sms_check=30 response: 30confirmation

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

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

version — current firmware version
example: version response: 1.01current version

save — save settings to the configuration file (without saving, settings are valid until the device restarts)
example: save response: 1 always

MONITORING

request — command to fetch a response (result of previous commands) from the device (the command performs no actions itself)

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

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

Integrating SIM Roulette into your project

We hope the information above helps you integrate SIM Roulette into your project without issues.
To simplify the task, we recommend using the SR-Navigator web panel and its API to interact with your software.
And of course, you can always use our developers’ services.