API SR-1640

Interaction with SIM Roulette
Terms and definitions
Control commands of SIM Roulette SR-1640
SIM banks
SIM cards
Modems
Screen
Sound
Motors
Sensors
Buffer
Settings
Mechanical settings
Monitoring
Errors
Statuses
Integrating SIM Roulette into your project

Interaction options 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 subsequent execution 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

Important! For a GET request, the URL must be encoded on the client side using the urlencode function.

SIM Roulette returns the response as plain text. 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, this may be a number or text. 0 is always encoded as NULL.

4). SIM Roulette calls the 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 — result of executing the command
and receives from the server the next command as text: {data}step#!#command
Important! {data} — a 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
H — hexadecimal number
X — numeric or character data
(in parentheses) denotes an optional command parameter

Control commands of SIM Roulette SR-1640

SIM BANKS

bank_select: D — select a SIM bank
D — bank range 0 – 15 (clockwise)
Example: bank_select:0

bank:X — configuring SIM bank parameters
X:
? — current SIM bank number (-1 if the device has just started and the current bank is not determined)
r — current bank position (rotation) along the R axis / r=D — set rotation
b — card receiver height (if a card receiver is installed in the SIM bank)
h — measure the relative height of the SIM card stack in the current bank
Example: bank:r=100

SIM CARDS

card_get — pick a card from the top of the stack in the current bank
see STATUSES, ERRORS

card_put — eject the card onto the top of the stack in the current bank
see STATUSES, ERRORS

card_out — eject the card through the output slot

card_insert(:D) — insert the card into the card receiver
D — SIM bank number with an installed card receiver (for bank 0, the number may be omitted)
Examples:
card_insert card_insert:2

card_retract(:D) — retract the card from the card receiver with prior lowering of the SIM card contacts (for bank 0, the number may be omitted)
Examples:
card_retract
card_retract:4

MODEM

modem[D]:rate — data rate to the modem (D – bank number, except 0) / modem_rate=D — set the rate

modem[D]:name — card receiver name (D – bank number, except 0) / modem[D]:name=W — enter the 4-character name of a previously linked card receiver (link:BRCST>id)

modem[D]:ping — PING the card receiver (D – bank number, except 0); the reply should be "pong", request ping:w is acceptable

modem[D]:step — number of drive steps of the card receiver required to raise/lower contacts / modem[D]:step=D — set the number of steps

modem:on — turn the modem on
(for a card receiver other than bank 0, specify the bank number. Example: modem[2]:on)

modem:off — turn the modem off
(for a card receiver other than bank 0, specify the bank number. Example: modem[2]:off)

modem:up — raise (connect) the SIM card contacts
(for a card receiver other than bank 0, specify the bank number. Example: modem[2]:up)

modem:down — lower (disconnect) the SIM card contacts
(for a card receiver other than bank 0, specify the bank number. Example: modem[2]:down)

modem:write=AT… — send a command to the modem (standard AT commands are sent to the modem this way)
(for a card receiver other than bank 0, specify the bank number. Example: modem[2]:write=AT)
Example: modem:ATD*110*10# (receive an SMS with the SIM card phone number from Beeline)

modem[D]:read — modem response (D – bank number) (for the 0th card receiver the command is not needed; all data received from the modem is immediately returned with step=0)

MOTOR CONTROL

drv_move:yX — control motor Y (vertical movement of the carriage)
X — range -20000 — 20000 (move up/down, lowest position = 0)
or >fix — lock the motor axis
or >nofix — unlock the motor axis
Examples:
drv_move:y-1000
drv_move:y>fix

drv_move:rX — control motor R (radial movement of the carriage)
X — range -1000 — 1000 (move forward/backward)
>fix — lock the motor axis
>nofix — unlock the motor axis
Example: drv_move:100

drv_move:xD — control motor X (moving the card on the carriage)
D — 1 out of the carriage / -1 into the carriage / 0 stop
Example: drv_move:x-1

drv_move:mD — control the magnet on the carriage
D — 1 turn on / 0 stop
Example: drv_move:0

MECHANICAL SETTINGS

drv_y:X — configure motor Y parameters (vertical carriage movement)
X:
p — current position / p=1 — set current position
re — current reverse status / re=1 — enable reverse / re=0 — disable reverse
sd — speed when moving down / sd=D — set speed
su — speed when moving up / su=D — set speed
up — offset from the sensor to the top of the stack when moving up / up=D — set offset
dw — offset from the sensor to the top of the stack when moving down / dw=D — set offset
to — lift above the stack when ejecting a card (card_put) / to=D — set lift
ho — bottom of the card stack (below this height the sensor does not see cards) / ho=D — set bottom
w — working position height / w=D — set height
e — ejection slot height / e=D — set height
m — maximum lift height / to=D — set height
t — allowed movement along the Y axis with an unfixed card / t=D — set tolerance
r — Y-axis shift on a repeated attempt to pick a card (card_get) / r=D — set shift
f — time delay in milliseconds to lock the Y axis when addressing the corresponding motor / f=D — set delay
Examples:
drv_y:to
drv_y:to=1000

drv_r:X — configure motor R parameters (radial carriage movement)
X:
p — current position / p=1 — set current position
re — current reverse status / re=1 — enable reverse / re=0 — disable reverse
sh — high speed / sh=D — set speed
sl — low speed / sl=D — set speed
or — right shift when positioning over sensor 0 / or=D — set shift
ol — left shift when positioning over sensor 0 / ol=D — set shift
o — shift when returning the carriage to sensor 0 / o=D — set shift
r — maximum rotation / r=D — set shift
f — time delay in milliseconds to lock radial movement when addressing motor R / f=D — set delay
Example: drv_r:f=5000

drv_x:X — get motor X parameters (moving the card on the carriage)
X:
re — current reverse status / re=1 — enable reverse / re=0 — disable reverse
g — get current status (0 / 1 / -1 see drv_move:x)
f — time of one iteration when moving forward / f=D — set time
b — time of one iteration on reverse stroke (analogous to ABS in a car, helps with slipping) / b=D — set time
i — number of attempts to insert a card into the card receiver / eject a card (card_insert / card_put) / i=D — set value
r — number of attempts to pick a card from the card receiver / bank (card_retract / card_get) / r=D — set value
s — rocking amplitude when inserting and picking a card / s=D — set amplitude
Example: drv _x:s

drv_m — get the magnet status on the carriage (0 / 1 see drv_move:m)
Example: drv_m

SENSORS

sensor: W — get sensor parameters
W:
y1 — lower sensor of motor Y (vertical carriage movement)
y2 — sensor detecting the top edge of the card stack
r1 — sensor of motor R (radial carriage movement)
x1 — sensor for locking motor X on the carriage
x2 — sensor for locking the card on the carriage
x3 — sensor for picking a card on the carriage
Example: sensor:y1

SCREEN

lcd_mode:X
X:
c — clear the screen
1 — turn backlight on
0 — turn backlight off
Example: lcd_mode:c

lcd_msg:W — display text up to 32 characters
W:
[text]
Example: lcd_msg:My text

lcd_txt:W — display text of arbitrary length (Latin only)
W:
[text]
Example: lcd_txt:My text

SOUND

sound:beep — short beep

sound:error — long tone

sound:alarm — a fragment of the “Imperial March” from the movie “Star Wars”

BUFFER

buffer_client:clear — clear the buffer of SIM Roulette command results

SETTINGS

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

connect_interval — interval (in milliseconds) between requests to the remote server / connect_interval=D — set interval
Example: connect_interval=1000

error — error code (see card_get, card_put)

report — command execution status (see card_get, card_put)

version — firmware version of the mechanics coprocessor

main_rate — connection speed of the processor–mechanics coprocessor on the processor side / mate_rate=D — set speed

mate_rate — connection speed of the processor–mechanics coprocessor on the coprocessor side / mate_rate=D — set speed

answer — response format / answer=D — set format:
0 — NULL/1 (TRUE/FALSE)
1 — 0/1 (TRUE/FALSE)
2 — echo of input data

debug=D enable(1) / disable(0) debugger

load_default — load factory mechanics settings

reset — Soft reset of mechanics

restart:W — reboot
W:
main — Soft reset of the main processor
mate — Hard reset of the mechanics coprocessor
Example: restart:main

carrier_time — host connection wait timer (upon expiration, reconnection to the Internet occurs) / carrier_time=D — set time

port_rate — RS-485 interface baud rate / port_rate=D — set rate

MONITORING

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

ERRORS

When receiving NULL, in some cases you can request additional error information (command error):

Errors while picking a card (see card_get)
201 — at the time of executing the command, the card is not fully on the carriage
202 — as a result of the command, the card is not fully on the carriage
203 — as a result of the command, the mechanism is not retracted onto the carriage; further carriage movement in any direction is impossible
204 — the card was not taken; the carriage is free

Errors while ejecting a card (see card_put)
301 — failed to position the carriage at the top of the stack
302 — failed to eject the card

STATUSES

Upon successful execution of some commands, you can request details (command report):

Statuses while picking a card (see card_get)
201 — at the time of executing the command, the card was already taken
202 — card pick completed normally
203 — the card was taken, but an additional attempt was required
204 — the card was taken, but two additional attempts were required (it is recommended to check the settings and, if necessary, calibrate the vertical carriage movement)
205 — the card was taken, but some difficulties occurred during picking (it is recommended to visually monitor the card picking process)

Statuses while ejecting a card (see card_put)
301 — at the time of executing the command, the carriage was already empty
302 — card ejection completed normally
303 — the card was ejected, but an additional clockwise rotation of the carriage was required
304 — the card was ejected, but an additional counterclockwise rotation of the carriage was required (it is recommended to check the settings and, if necessary, calibrate the horizontal carriage movement)
305 — the card was ejected, but two additional counterclockwise rotations of the carriage were required

Integrating SIM Roulette into your project

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