API SR-Nano

Interaction with SIM Roulette
Terms and definitions
Control commands for SIM Roulette SR-Nano-500/1000
SIM cards
Tracks
Modem
SMS
Display
Sound
Remote
Variables
Files
Macro management
Settings
Monitoring
Integrating SIM Roulette into your project

Options for interacting with SIM Roulette

1). Direct command entry via the SIM Roulette web-interface terminal.

2). Creating command lists via the SIM Roulette web interface (Macros) and subsequent execution by the device.

3). 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 — code word set via the aggregator’s web interface
step — command sequence number (step)

command — command

SIM Roulette returns the response in plain text. Example: step#!#result
#!# — separator
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 may be a number or text. 0 is always encoded as NULL.

4). SIM Roulette polls 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 passes GET parameters:
step — response to the request with the number (step)
data — command execution result
and receives from the server the next command as text: {data}step#!#command
Important! {data} — 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 the results of dozens of commands.
0 is always encoded as NULL.
Most commands return: 1 — success, NULL — failure.

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

Control commands for SIM Roulette SR-Nano-500/1000

Tracks

In SR-Nano-500 there are 8 tracks, from 0 (A) to 7 (H). Cards are placed on the tracks. On A — 100 cards, on B — 90, on C — 80, on D — 68, on E — 58, on F — 46, on G — 34, on H — 24.

In SR-Nano-1000 there are 12 tracks, from 0 (A) to 11 (M). Cards are placed on the tracks. On A — 140 cards, on B — 130, on C — 120, on D — 110, on E — 100 cards, on F — 90, on G — 80, on H — 68, on I — 58, on J — 46, on K — 34, on L — 24.

track:W — track
W — parameter:

SIM cards

card:W — select a SIM card
W — parameter:

card>next[:W] — select the next SIM card
W — optional parameter:

card>prev[:W] — select the previous SIM card
W — optional parameter:

card>now — get the index of the currently selected SIM card (A0-H23/L23).
example: card>now response: A0card index 0no card selected
Note: the card index is always shown in the status line on the device screen and in the web interface.

card>discover — check for a SIM card in the current disk slot
example: card>discover response: 1card present 0no card

card>begin — mark the current SIM card as the first in the subsequent operation cycle; in this case, at the end of the cycle (e.g., after a full pass) the program will stop before this card
example: card>begin response: 1done 0error

card>out:W — move the card (for manual extraction) to the arrow-marked position on the track (the screen shows the track letter with the card number)
W — parameter:

GSM MODEM

modem>connect — connect contacts to the current SIM card
example: modem>connect response: 1done 0error
Note: does not work until a SIM card is selected. When connected, a corresponding icon is shown in the status line on the device screen and in the web interface.
Important! Always visually check that the contacts are disengaged (lifted) when changing the disk container. If necessary, quickly lift the contacts by pressing the multifunction touch button.

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

modem>outside — extend contacts without position check (service command) new!
example: modem>outside response: 1always
Important! use this command ONLY during technical maintenance of the aggregator!

modem>inside — retract contacts (service command) new!
example: modem>inside response: 1always

modem>on — power on the modem
example: modem>on response: 1always
Note: when the modem is on, a lightning icon is shown in the status line on the device screen and in the web interface

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

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

modem>activation[:bool] — connect to the SIM card and activate the modem with check new!
:bool — optional parameter that simplifies the response to 1 (True) / NULL (False). Statuses 1 and 5 are considered successful.
examples: modem>activation response: 1;9;MTSsuccessful network attach status;time spent in seconds;operator 4;7network attach error;time spent in seconds
modem>activation:bool response: 1done 0error Note: does not work until a SIM card is selected. Connection/reconnection and modem power-on are performed automatically. more about statuses

modem>set:step — number of steps of the contact drive required 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 modem / 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 pdu/txt / modem>set:mode=pdu — set 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 for processing certain modem-interacting commands

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

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

modem>download:URL;FILE[;SIZE] — download a file from a website and upload it to the modem’s storage (for modems supporting this functionality, e.g., SIM800) 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 0none

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 — recipient number
W — SMS text (Latin/Russian characters are detected automatically)
example: sms>send:+79001234567;SMS text response: 1SMS sent 0command syntax error
Note: the command sends single-part SMS

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

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 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; you can use bbcode to form tables: [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 automatically set the font size and, if needed, paginated output)
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 {a}, {b} etc.; to substitute a character use {32}, {147} etc.

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

buffer>postfix=W — append data to the current buffer text
example: buffer>write= end of line response: 1always
Important! To substitute a variable value use {a}, {b} etc.; to substitute 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 the contents of the buffer and the saved stack copy
example: buffer>swap response: 1buffer has data 0buffer empty

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

buffer>ussd — copy into the buffer the last modem response to a USSD request (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 to the buffer the internal timestamp (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 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>fs>save>operator — write buffer contents to the “Operator” field -> to the current SIM card’s row -> into the current track’s configuration file (/c/_disk_name_/_track_)
example: buffer>fs>save>operator response: 1done 0error

buffer>fs>load>operator — read the “Operator” field from the configuration file into the buffer
example: buffer>fs>load>operator response: 1buffer has data 0buffer empty

buffer>fs>save>phone — write buffer contents to the “Phone number” field -> to the current SIM card’s row -> into the current track’s configuration file
example: buffer>fs>save>phone response: 1done 0error

buffer>fs>load>phone — read the “Phone number” field from the configuration file into the buffer
example: buffer>fs>load>phone response: 1buffer has data 0buffer empty

buffer>fs>save>balance — write buffer contents to the “Balance” field -> to the current SIM card’s row -> into the current track’s configuration file
example: buffer>fs>save>balance response: 1done 0error

buffer>fs>load>balance — read the “Balance” field from the configuration file into the buffer
example: buffer>fs>load>balance response: 1buffer has data 0buffer empty

buffer>fs>save>comment — write buffer contents to the “Comment” field -> to the current SIM card’s row -> into the current track’s configuration file
example: buffer>fs>save>comment response: 1done 0error

buffer>fs>load>comment — read the “Comment” field from the configuration file into the buffer
example: buffer>fs>load>comment response: 1buffer has data 0buffer empty

buffer>sim>save>phone — write buffer contents to the 1st phonebook entry named “SR” on the current SIM card
example: buffer>sim>save>phone response: 1done 0error

buffer>sim>load>phone — read into the buffer the number from the 1st phonebook entry named “SR” on 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 in the buffer for a character sequence; 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 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 0not found — if 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 — test for the presence of 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] — test for a number with the specified (D) number of digits, example: buffer>test:[d10] response: 110-digit number found 0not found
[sD] — selection test for the specified (D) number of characters from the start or (-D) from the end (Russian characters take 2 bytes), example: buffer>cut:[s10] — only the first 10 characters remain in the buffer, response: 1specified number of characters present 0specified number of characters not found

buffer>cut:W — search in the buffer for a character sequence; remove the found fragment from the buffer contents
W — search string:
* — matches any number of arbitrary characters, example: buffer>cut:rub.* — if the buffer contains the word “rub.” it and everything after will be removed, 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 0not found — if found, the number 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 cut from the buffer, response: 1cut performed 0specified number not found

DISK CONTAINER

disk>name — current disk name (the disk name is stored in the device’s non-volatile memory; after changing the disk, read the name from the SIM card memory in A0) disk>name=W — assign a disk name (up to 16 characters: Latin letters, digits)
examples: disk>name response: defaultcurrent disk name
disk>name=new_disk response: new_diskentered disk name

disk>name>load — read the disk name from the SIM card memory at A0
example: disk>name>load response: 1done 0error

disk>name>save — save the disk name to the SIM card memory from A0
example: disk>name>save response: 1done 0error

disk>clear — delete all information about SIM cards on the disk (delete corresponding configuration files)
example: disk>clear response: 1always

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~Русский текст}! — depending on the selected language, the corresponding variant 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:beep response: 1always

REMOTE

key>discover — check the possibility of remote control (in SR Nano, remote/web control is mutually exclusive; to activate the remote at power-up, press any remote button)
example: key>discover response: 1control possible 0control not possible

key — remote poll (the response will return 1 if any button was pressed; the name of the pressed key 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 — 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’s value into the buffer, use {a}, {b} ... {z}.

FILES

The filesystem 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 card may additionally be used.

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

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

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

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

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

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

sd>remove:W — delete file on SD card
W — file name
example: sd>remove:/test/file.txt response: 1done 0error

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

sd>rename:W — rename file on SD card
W — current path and file name _ new path and file name
example: sd>rename:/terminal.dat /test/terminal.dat response: 1done 0error

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

fs>sd>copy:W — copy file from internal memory to SD card
W — source file name _ destination file name
example: fs>sd>copy:/terminal.dat /test/terminal.dat response: 1done 0error

sd>fs>copy:W — copy file from SD card to internal memory
W — source file name _ destination file name
example: sd>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 filesystem
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 filesystem
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 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 launched in the Macros section of the SR-Nano web interface; you can also track the progress of a running macro there.

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

SETTINGS

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

answer>clear — clear the response buffer
example: answer>clear response: 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 response: 1allowed 0forbidden

carrier_time — idle time (in seconds) between commands; after the timer expires SIM Roulette reconnects to the network / carrier_time=D — set the 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

port_rate> — RS-485 interface speed (for models that support it) / port_rate=D — set speed
example: port_rate=38400 response: 38400confirmation

sms_check — interval (in 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 of incoming SMS and USSD responses; enter pdu to see the current setting
example: pdu response: 1enabled 0disabled

debug — enable (debug=1) or disable (debug=0) output of debug information (e.g., macro execution progress) on the device screen; enter debug to see 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, the settings are active until the device is rebooted)
example: save response: 1 always

MONITORING

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

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 web panel SR-Navigator and the API to interact with your software.
And of course, you can always use the services of our developers.