Technical documentation ❯ API of SimRoulette aggregators with legacy firmware ❯

API SR-Organizer-Smart

Interaction with SIM Roulette
Terms and Definitions
Control Commands of SIM Roulette SR-Organizer
Modems
SMS
Screen
Sound
Variables
Files
Settings
Control Commands
Monitoring
Macros
Scheduler (CRON)
Integrating SIM Roulette into Your Project

Ways to interact with SIM Roulette

1). Direct input of a command through 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). GET or POST request to SIM Roulette of the form http://XXX.XXX.XXX.XXX/port?token=$token&command=$command

XXX.XXX.XXX.XXX — SIM Roulette IP address
$token — passphrase set via the aggregator WEB interface
$command — command
Important! "." (dot) before the command tells the aggregator that the controlling device expects a response to the command; otherwise the command will be executed but no response will be placed in the output stream.
If no detailed response is needed and only the result is required, put "@" before the command.

4). SIM Roulette contacts the 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:
data — result of command execution
and receives from the server the next command as plain text:
{data}command
Important! {data} — required prefix so SIM Roulette understands the server returns valid data.

The server URL is specified in the WEB interface or set by the server_url command; the frequency of contacting the server is configured in the WEB interface or set by the server_fr command.

SIM Roulette returns responses in JSON format. Example: {"result":"[RESULT]"}
Result of command execution (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.
Responses are asynchronous. In addition to responses to commands with the "." prefix, the output stream also receives status messages about current modems and events occurring on the aggregator’s system devices (modems, buttons, etc.).

Example:
request: http://192.168.1.2/port?token=12345&command=.version
Important! In a GET request the command parameter in the URL must be encoded on the client side with urlencode.
response: {"result":"1.69"}command_execution_result

Several commands can be combined using &&. In this case they will be executed sequentially.

Example:
request: http://192.168.1.2/port?token=12345&command=.version%26%26.set.dev.ip
Note! Since the command parameter is urlencode-encoded, here && becomes %26%26.
responses:
{"result":"1.69"}result_of_first_command
{"result":"192.168.1.2"}result_of_second_command

For easier navigation in aggregator responses, any command can be signed by adding the parameter "sign":"[SIGNATURE]". In this case the response will also contain the specified signature.

Example:
request: http://192.168.1.2/port?token=12345&command=.version:{"sign":"test"}
response: {"result":"1.69","sign":"test"}command_execution_result

Any value in the aggregator’s response can be output as the result by adding the parameter "result":"[KEY]" to the command.

Example:
request: http://192.168.1.2/port?token=12345&command=.version:{"sign":"test","result":"sign"}
response: {"result":"test"}command_execution_result

Terms and Definitions

Command parameters can be passed sequentially separated by commas or in JSON format.
Example:

sms.send:number(1),sms(2)[,modem=1(3)]

Passing parameters sequentially, separated by commas (1, 2, 3), parameter in [brackets] is optional: sms.send:+79001234567,Text of SMS
Passing parameters in JSON (number, sms, modem), parameter in [brackets] is optional: sms.send:{"number":"+79001234567","sms":"Text of SMS","modem":"1"}

SIM Roulette returns responses asynchronously.
The SIM Roulette response buffer is dynamic and may contain results of dozens of commands.
0 is always encoded as NULL.
Most commands in result return: 1 — executed, NULL — error.

Throughout the text:
D — number, example: 33
W — word, text data, example: Text
X — numeric or text data
(D) — parameter sequence number, example: fs.rename:source(1),target(2)

Thus the command fs.rename:/terminal.dat,/test/terminal.dat is equivalent to fs.rename:{"source":"/terminal.dat","target":"/test/terminal.dat"}

[W] — optional parameter, example: sms.send:number(1),sms(2)[,modem(3)]
=X — default value of optional parameter, example: ussd:number(1)[,modem(2)=1]
{D...D} — allowed range of values, example: {-23...23}

Control Commands of SIM Roulette SR-Organizer

MODEMS

modem.on — turn on modem(s)
example: modem.on response: 1always

modem.off — turn off modem(s)
example: modem.off response: 1always

modem[D].status — force status output of the first or specified modem (D)
Note! When a modem’s status changes, the aggregator automatically outputs the status to the output stream.
example: modem2.status response: 1power on 0power off

modem[D].card:X — select SIM card
1-16 or 1-24 in devices with one modem
A1-C8 by the modem serving that card range
1-8 by the specified modem (D) in devices with multiple modems
examples:
modem.card:16 response: 1done 0error
modem.card:A8 response: 1done 0error
modem3.card:7 response: 1done 0error

call:number(1)[,modem(2)=1] — outgoing call from the current SIM of the specified modem
examples:
call:+79001234567 response:1done 0error
call:{"number":"*102#","modem":"2"} response:1done 0error

ussd:number(1)[,modem(2)=1] — USSD request from the current SIM of the specified modem
examples:
ussd:*102# response:1done 0error
ussd:{"number":"*102#","modem":"2"} response:1done 0error

command:action(1)[,modem(2)=1] — predefined action (answer, hangup)
examples:
command:answer,3 — answer incoming call of modem 3, response:1done 0error
command:{"answer":"hangup","modem":"2"} — hang up modem 2, response:1done 0error

modem[D].send:AT… — direct command to the first or specified modem (D)
Note! This way you can send standard AT-commands
example: modem2.send:ATD+79001234567; response: 1always

SMS

sms.send:number(1),sms(2)[,modem(3)=1] — send SMS from the current SIM of the specified modem
examples:
sms.send:+79001234567,Text of SMS,3 response:1done 0error
sms.send:{"number":"+79001234567","sms":"Text of SMS"} response:1done 0error

SCREEN

When 7-segment indicator is present

set.display:[light_min{1...100}][,light_max(1...100}] — set min and max brightness (switching happens automatically)
examples:
set.display:{"light_min":"10"}, response: 1done 0error
set.display:{"light_min":"10","light_max":"80"}, response: 1done 0error

display:W{ABCDEFGH} — output symbol on indicator (segment map shown)
examples:
display:BC → shows "1", response:1done 0error

display.clear — clear indicator
example: display.clear response:1always

With OLED display connected

display.clear — clear display
example: display.clear response:1always

display:W — output text and symbols to display
W — params separated by "::":
1 — font size 10,16,24
2 — align (L,C,R)
3 — X position (0—127)
4 — Y position (0—63)
5 — text ({English~Русский}) depending on UI language
(6) — optional "|" for multiline

With LCD Control Module

display.clear:[D{1...4}] — clear screen fully or specific line
examples:
display.clear → 1
display.clear:1 → 1

display.print:W — print text
example: display.print:Text → 1/0

SOUND

sound:beep — short beep
sound:error — long error tone
Responses: 1 always

BUFFER

Device text buffer is a powerful tool for parsing input, forming output and commands.

buffer.clear — clear buffer
buffer.view — show buffer contents
buffer.raw — show raw contents
buffer.display — show buffer on display
buffer.write:W — write data
buffer.prefix:W — prepend data
buffer.postfix:W — append data
buffer.push — save to stack
buffer.pop — restore from stack
buffer.swap — swap buffer with stack
buffer.merge[=W] — merge with stack
buffer.time — append current time
buffer.date — append current date
buffer.timestamp — append timestamp
buffer.find:W — search
buffer.test:W — test
buffer.cut:W — cut
Responses: 1/0 depending on match.

VARIABLES

var:W[=D|+D|-D|*D|/D|==D|<D|>D] — work with numeric variables a..z
Examples: var:a=123, var:a+1, var:a==33 etc. → responses numeric or 1/0

var:str1/str2/str3 — string variables
Examples: var:str2=buffer, var:buffer=str3

FILES

Internal flash FS (1.5–2.5 MB), sometimes microSD.
fs.space — free/used/total
fs.list:/ — list folder
fs.view:file — view file
fs.edit:file — edit file
fs.delete:file — delete file
fs.rename:src,tgt — rename
fs.copy:src,tgt — copy
fs.download:url,file — download
fs.upload:url,file[,name] — upload

SETTINGS

version — firmware version
set.dev.serial — serial number
set.dev.rev — HW revision
set.dev.ip — IP
set.carrier_timer — idle reconnect
set.server:url,fr — server URL
set.dev.mode — SMART/MANUAL
set.dev.alert — terminal alerts
set.ntp_server — ntp
set.time.zone — timezone
set.time.daylightOffset — DST offset
set.httpupdate — check updates
save — save settings

CONTROL COMMANDS

answer.clear — clear answers
command.clear — clear commands
i2c — list devices
restart — soft reset
load_default_settings — reset to defaults
hard_reset — factory reset

MONITORING

request — get result
email.send:email,text — send email

MACROS

macro:W[,W2] | m:W[,W2] — run macro
macro.stop | m.stop — stop
macro.event:event,macro,action — add/remove event listener
Events: outCall, inCall, noCarrier, answer, hangUp, ussd, smsAlert, smsReceived, modemState, modemAnswer, key, portChangeState, timer1, timer2, dtmf, callBegin, callEnd, smsSent, smsNotSent

SCHEDULER (CRON)

Classic CRON in /crontab
* * * * * macro:label
Supports @hourly, @daily, @weekly, etc.

Integrating SIM Roulette into Your Project

We hope this information helps integrate SIM Roulette into your project.
To simplify, use the SR-Navigator web panel and its API.
You can also use our developers’ services.

Authorization

Login