API SR-Organizer

Interaction with SIM Roulette
Terms and definitions
Control commands of SIM Roulette SR-Organizer
Modems
SMS
Variables
Files
Macro management
Settings
Monitoring
Integrating SIM Roulette into your project

Interaction options with SIM Roulette

1). Directly enter a command via the SIM Roulette web interface terminal.

2). Create lists of commands (Macros) via the SIM Roulette web interface and then have the device execute them.

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
|| — delimiter
token — code word set through the aggregator’s web interface
step — sequential command number (step)

command — the command

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

4). SIM Roulette contacts a 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 the number (step)
data — command execution result
and receives the next command from the server as text: {data}step#!#command
Important! {data} — the required prefix so that SIM Roulette understands the server is returning valid 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 symbolic data
(in parentheses) indicates an optional command parameter

Control commands of SIM Roulette SR-Organizer

MODEMS

modem>on — turn on the modems
example: modem>on answer: 1always
Note: when a modem is on, a lightning icon appears in the device screen status bar and in the web interface

modem>off — turn off the modems
example: modem>off answer: 1always

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

modem>activation[:D] — connect to a SIM card and activate the specified [D] modem or both modems with verification
examples:
modem>activation answer: 1;MTS;1;MEGAFON;9successful network attach status of modem 1;operator of modem 1;successful network attach status of modem 2;operator of modem 2;elapsed time in seconds 4;;0;;7network attach error of modem 1;;network attach error of modem 2;;elapsed time in seconds
modem>activation:2 answer: 1;MTS;9successful network attach status of modem 2;operator of modem 2;elapsed time in seconds 4;;0;;7network attach error of modem 2;;elapsed time in seconds more about statuses

modem>select:D — select the default modem for interaction (1-2)
example: modem>select:2 answer: 2selection confirmed 0invalid modem number

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

modem>set:mode — modem operating mode pdu/txt / modem>set:mode=pdu — set mode
examples: modem>set:mode answer: pducurrent mode
modem>set:rate=txt answer: txtset mode
Note: information about the current modem mode is needed by the aggregator to process some modem-interacting commands

modem>set:auto — auto power-on mode for modems / enabled (modem>set:auto=1) or disabled (modem>set:auto=0)
examples: modem>set:auto answer: 1current mode
modem>set:auto=1 answer: 1auto power-on set

modem>send:AT… — send a command to the selected modem (standard AT commands are sent to the modem this way)
example: modem>send:ATD+79001234567; answer: 1always
Note: all commands starting with the AT prefix are redirected by the aggregator to the selected modem, so the modem>send: construct is not required.
Note: responses from both modems arrive asynchronously with Step 0; responses from modem 1 have the 1: prefix, responses from modem 2 have the 2: prefix

modem[D]>send:AT… — send a command to the specified [D] modem
example: modem[2]>send:ATD+79001234567; answer: 1always
Note: responses from both modems arrive asynchronously with Step (step) 0; responses from modem 1 have the 1: prefix, responses from modem 2 have the 2: prefix

modem>card:D — select a card (1-8) for the default modem
example: modem>card:7 answer: 7selected card

modem[D]>card:D — select a card (1-8) for the specified [D] modem
example: modem[2]>card:6 answer: 6selected card

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

modem>pack:W##M##D — batch execution of a command by both or specified modems
W — AT command
M — modems that must execute the command (1;2 or all)
D — 1-wait for the response and return it, 0-send the command for execution without waiting for modem responses
example: modem>pack:AT+COPS?##all##1 answer:1##AT+COPS?
+COPS: 0,0,"Bee Line GSM"
OK
#1#2##AT+COPS?
+COPS: 0,0,"MTS"
OK
#1##1# — delimiter

modem>download:URL;FILE[;SIZE] — download a file from a website and upload it into the memory of the default modem
example: modem>download:simroulette.com/download/voice.amr;C:\User\voice.amr; answer: 1done 0error

SMS

sms>discover — check the flag indicating the presence of SMS on SIM cards connected to the modems
example: sms>discover answer: 1present 0absent
Note: after switching the card in one of the modems, the new-message flag is reset

sms>read[:D] — copy one SMS from the SIM card connected to the default modem or the specified [D] modem into the buffer and delete the copied SMS from the SIM card
example: sms>read answer: 1SMS copied 0no SMS

sms>send:X;W — send an SMS from the default modem
X — subscriber number
W — SMS text (Latin/Russian characters are detected automatically)
example: sms>send:+79001234567;SMS text answer: 1SMS sent 0command syntax error
Note: the command allows sending single SMS

sms>send>buffer — send an SMS from the default modem using the buffer (number;text)
example: sms>send>buffer answer: 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 answer: 1always

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

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

buffer>display — display the buffer contents on the device screen (depending on the data size, the device will auto-adjust font size and, if needed, paginate)
example: buffer>display answer: 1always

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

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

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

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

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

buffer>swap — swap the buffer contents and the saved copy in the stack
example: buffer>swap answer: 1buffer has data 0buffer is empty

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

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

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

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

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

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

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

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

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

buffer>sim>save>phone — write buffer contents to the 1st phonebook cell named "SR" of the current modem’s SIM card
example: buffer>sim>save>phone answer: 1done 0error

buffer>sim>load>phone — read into the buffer the number from the 1st phonebook cell named "SR" of the current modem’s SIM card
example: buffer>sim>load>phone answer: 1buffer has data 0buffer is empty

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

buffer>answer:grab=D — enable (1) / disable (0) capturing device responses into the buffer
examples: buffer>answer:grab=1 answer: 1device response capture enabled
buffer>answer:grab=0 answer: 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:баланс* — if the buffer line contains the word "баланс" (balance), the buffer will keep the text from "баланс" to the end of the line, answer: 1search string found 0no matches
[dD] — search for a number with the specified (D) number of digits, example: buffer>find:[d10] answer: 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 occupy 2 bytes), example: buffer>find:[s10] — only the first 10 characters remain in the buffer, answer: 1done 0not done

buffer>test:W — check for a character combination in the buffer
W — search string:
* — matches any number of arbitrary characters, example: buffer>test:баланс* answer: 1search string found 0no matches
[dD] — check for a number with the specified (D) number of digits, example: buffer>test:[d10] answer: 110-digit number found 0nothing found
[sD] — selection of the specified (D) number of characters from the start of the line or (-D) from the end (Russian characters occupy 2 bytes), example: buffer>cut:[s10] — the buffer will contain only the first 10 characters, answer: 1the specified number of characters is present 0the specified number of characters not found

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

VARIABLES

var>W[=D|+D|-D|*D|\D|==D|<D|>D] — work with a variable
W — numeric variable name (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 construct {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 answer: 100000free memory size in bytes

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

fs>view:W — view a file
W — file name
example: fs>view:/terminal.dat answer: ❱❱ ENTERING VIEW MODE 0error

fs>edit:W — edit a file
W — file name
example: fs>edit:/terminal.dat answer: ❱❱ ENTERING EDITOR 0error

fs>remove:W — delete a file
W — file name
example: fs>remove:/test/file.txt answer: 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 answer: 1done 0error

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

fs>sd>copy:W — copy a file from internal memory to the SD card
W — source file name _ destination file name
example: fs>sd>copy:/terminal.dat /test/terminal.dat answer: 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 answer: 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 answer: 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 answer: ❱❱ RUNNING MACRO 0error
m:filename answer: ❱❱ RUNNING MACRO 0error
macro:file_{a} answer: ❱❱ RUNNING MACRO 0error
Note: macros can be edited and launched in the Macros section of the SR-Nano web interface; you can also track the execution progress of a running macro there.

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

SETTINGS

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

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

busy_enable — allow (busy_enable=1) or forbid (busy_enable=0) the device to ignore network requests while performing mechanical actions; enter busy_enable to see the current setting
example: busy_enable answer: 1allowed 0forbidden

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

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

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

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

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

debug — allow (debug=1) or forbid (debug=0) output of debug information (e.g., macro execution progress) to the device screen; enter debug to see the current setting
example: debug answer: 1enabled 0disabled

version> — current firmware version
example: version answer: 1.01current version

save — Save settings to the configuration file (without saving, the settings are valid until the device is rebooted)
example: save answer: 1 always

MONITORING

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

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

restart — Soft reset of the device
example: restart answer: 1 ❱❱ DEVICE REBOOT

Integrating SIM Roulette into your project

We hope the information above helps you integrate SIM Roulette into your project without problems.
To make things easier, we recommend using the SR-Navigator web panel and API to interact with your software.
And of course, you can always use the services of our programmers.