Cybrotech GSM-1 User manual

G
GS SM M- -1 1 U Us se er r M Ma an nu ua al l
rev. 1.10
applies to GSM-1 v3.0, v3.1 and v3.2
use CyPro 2.6.0 or later
Cybrotech Ltd © 2010-2014

I
In nd de ex x
Index............................................................................................................................................1
Overview .....................................................................................................................................2
Quick setup .................................................................................................................................3
1. Insert SIM......................................................................................................................3
2. Edit configuration file.....................................................................................................3
3. Send configuration file ..................................................................................................3
4. Check operation............................................................................................................4
Connection options......................................................................................................................6
Configuration...............................................................................................................................7
Description........................................................................................................................7
Configuration file...............................................................................................................7
Input/output variables..................................................................................................................9
Input/output.......................................................................................................................9
Status bits .........................................................................................................................9
Status words .....................................................................................................................9
Module info........................................................................................................................9
Incoming voice call and SMS............................................................................................9
Outgoing voice call and SMS............................................................................................9
Push message ..................................................................................................................9
Basic functions..........................................................................................................................10
SMS read/write................................................................................................................10
Alarm function.................................................................................................................10
Incoming voice call..........................................................................................................11
Outgoing voice call..........................................................................................................11
Working with plc program..........................................................................................................12
Incoming SMS.................................................................................................................12
Outgoing SMS.................................................................................................................12
Incoming voice calls........................................................................................................12
Outgoing voice calls........................................................................................................12
VoiceAndSMSAPI variables............................................................................................12
Wiring schematics.....................................................................................................................13
Digital inputs, 24V output................................................................................................13
Output using 230V contactor ..........................................................................................13
Output using 230V bistable relay....................................................................................13
Technical specifications ............................................................................................................14
Mounting .........................................................................................................................14
Class B operation............................................................................................................14
LED signalization ............................................................................................................14
Versions and upgrade...............................................................................................................15

O
Ov ve er rv vi ie ew w
GSM-1 is GSM/GPRS module for CyBro-2. Basic functions are:
SMS
- read and write CyBro variables
- send SMS when a variable is set
Voice
- call module to perform an action
- perform call when condition is satisfied
GPRS
- remote programming and monitoring with CyPro
- remote data transfer with CyBro OPC server
GSM-1 connects to IEX bus, together with other i/o modules. CyBro serial port is not used.
To use GSM-1, no programming is needed. Set a few configuration options, and module is ready.
Hardware:
- three-band 900/1800/1900MHz
- internal GSM antenna
- external antenna connector (SMA type), automatic switch
- 4 analog/digital inputs
- 2 relay outputs
Unlike other IEX modules, only a single GSM-1 can be connected to CyBro.
For a different product versions, please check "Versions and upgrade" chapter.

Q
Qu ui ic ck k s se et tu up p
1
1. . I In ns se er rt t S SI IM M
Open front cover and insert SIM in card holder.
2
2. . E Ed di it t c co on nf fi ig gu ur ra at ti io on n f fi il le e
Edit configuration file (CyPro/Examples/GsmIniDemo.ini) according to your data:
C
Co om mm mo on n
If your SIM card asks for a PIN, uncomment SimPin and enter correct PIN number.
[GSM]
SimPin=1234
V
Vo oi ic ce e
Enter your mobile phone number in OutgoingPhones group.
[OutgoingPhones]
[phone]
G
GP PR RS S
- Make sure that SIM card is data-enabled, ask your GSM provider for details.
- Set Apn, UserId, Password and DnsIp according to data provided by your GSM provider.
- Set NAD to network address of your CyBro. Use serial number, not alias.
- Set PushIp to IP address (or domain name) where push message should be sent.
[GPRS]
Apn=data.vip.hr
UserId=38591
Password=38591
DnsIp=212.91.97.3
[Push]
NAD=8031
PushIp=myhome.getmyip.com
3
3. . S Se en nd d c co on nf fi ig gu ur ra at ti io on n f fi il le e
- Connect CyBro, GSM-1, power supply and ethernet.
- Start GsmLoader, select CyBro and GSM-1.
- Open and send GsmIniDemo.ini.
- Close GsmLoader (don't skip this).
- Start CyPro.
- Open GsmIniDemo.cyp, autodetect and start.

After transfer is complete, module will reset automatically. Minute or two later, it will connect to network, and
both GSM and GPRS LEDs will be green. If configuration file has errors, GSM LED will blink.
4
4. . C Ch he ec ck k o op pe er ra at ti io on n
S
SM MS S
Send SMS "cybro_qx02=1" to GSM-1.
In a few seconds, relay will turn on. Confirmation message (if configured) will be received soon.
V
Vo oi ic ce e
- Open variable monitor.
- Call GSM-1 from your mobile phone.
- Variable gsm_incoming_call becomes 1, and gsm_incoming_rings increments on each ring. Calling number
will be displayed in array of variables incoming_number.
- Set gsm_outgoing_index to 0 and gsm_outgoing_call_req to 1 (will reset automatically). Your phone will ring.
G
GP PR RS S
- Make sure GSM module is configured to your WAN address (check http://www.whatismyip.com).
- Configure router to forward UDP port 8442 to your PC.
- Start CyBroPushServer, wait until push message appears.

- Remember CyBro IP address and port number, and close CyBroPushServer (don't skip this).
- Start CyPro, open GsmIniDemo.cyp.
- Configure communication for WAN, using push connection. Turn on Extra retries for unreliable connection.
You may also need Extra timeout for slow connection.
- Open Configuration and enter IP address and port number from push server.
Status bar will show when communication is established.

C
Co on nn ne ec ct ti io on n o op pt ti io on ns s
1. PC-CyBro using VPN SIM cards
2. CyBro-CyBro using VPN SIM cards (UDP broadcast support is required)
Note: VPN should be configured to pass broadcast messages.
3. PC-CyBro using Internet connection
Note: Symbol represent a known address, static IP or dynamic DNS.
4. PC-CyBro and Web-CyBro using CyBroWebCms

C
Co on nf fi ig gu ur ra at ti io on n
D
De es sc cr ri ip pt ti io on n
GSM-1 is configured by sending configuration ini file. Use text editor to edit, and GsmLoader to send file.
Configuration depends on plc program. When allocation is modified, configuration file should be updated.
Parameters are divided by groups. The group name appears in square brackets ([ ]). Semicolon (;) is used to
comment a line. Comment continue to the end of the line, everything between semicolon and end of line is
ignored.
Maximum size of configuration file is 14Kb. Special or national characters are not allowed, and may cause
parsing error.
C
Co on nf fi ig gu ur ra at ti io on n f fi il le e
C
Co om mm mo on n
[GSM]
SimPin=1234
UssdCredit= *101#
CreditLowLimit=5
SimPin is needed if PIN of your SIM card is not disabled.
UssdCredit is string for checking credit limit, defined by gsm operator. Below CreditLowLimit GSM led will
begin blinking. Credit is asked once per hour. If UssdCredit doesn't exist, checking is not performed.
Note: Be aware that prepaid SIM cards have limited period of validity, expiring of which module can't detect.
When in doubt, check SIM in your mobile phone.
[IncomingPhones]
[phone]
[phone]
IncomingPhones contains list of phone numbers (international format, beginning with '+'), allowed to call or
send SMS to module. If group doesn't exist, everybody have access. If group exist, but it is empty, no one will
be able to access.
[OutgoingPhones]
[phone]
[phone]
OutgoingPhones contains list of phone numbers (international format, beginning with '+'), which will be called
(or sent SMS) in case of an alarm.
S
SM MS S r re ea ad d/ /w wr ri it te e
[SMS]
;enable confirmation for SMS write, 0-don't send, 1-send confirmation
ControlAck=1
ControlAck tag defines weather SMS write confirmation is sent or not.
[CybroVars]
cybro_qx00=1024,1
cybro_iw00=2048,2
my_counter=6144,3
List of accessible CyBro variables. Variables are used for SMS read/write, or as a content of an alarm
message. Use address from allocation file (.alc), generated by CyPro. Alc file contains hexadecimal address,
so it should be converted to decimal. Variable type is 1-bit, 2-int, 3-long and 4-real.

A
Al la ar rm m f fu un nc ct ti io on n
[SMSAlarmTrigger]
1024
1025
[SMSAlarmText]
Alarm: fire in cellar! CO=%co_measured:1%
Alarm: valve %valve is broken! Pressure is %pressure:2
Alarm is sent when trigger variable is set to 1. Module will automatically reset variable to 0.
V
Vo oi ic ce e f fu un nc ct ti io on n
[Voice]
;0-leave incoming call ringing, 1-hangup after first ring
RxHangup=0
RxHangup tag defines weather the incoming call is leave ringing or hanged up.
G
GP PR RS S f fu un nc ct ti io on n
[GPRS]
GPRSEnable=1 ; Global control to enable or disable GPRS.
Apn=gprs0.vipnet.hr
UserId=38591
Password=38591
DnsIp=212.91.97.3
Apn, UserId, Password and DnsIp are provided by GSM operator.
[Push]
NAD=8031 ; CyBro NAD (serial number, not alias).
PushIp=89.1.3.96; IP address or domain name to which push is sent.
PushPort=8442 ; Port to which push is addressed, use 8442.
PushPeriod=60 ; Period of the push repetition in seconds.
Push group is used for push message. Purpose of push message is to get IP address of CyBro.

I
In np pu ut t/ /o ou ut tp pu ut t v va ar ri ia ab bl le es s
I
In np pu ut t/ /o ou ut tp pu ut t
gsm_ix00..gsm_ix03 - digital inputs, 0-off, 1-on
gsm_iw00..gsm_iw03 - analog inputs, voltage 0..10V, 0..1023
gsm_qx00..gsm_qx01 - relay outputs, 0-off, 1-on
note: digital and analog inputs share same terminals
S
St ta at tu us s b bi it ts s
gsm_general_error - one or more system errors occurred (timeout, program or bus error)
gsm_timeout_error - communication failed, no messages are coming from the module
gsm_program_error - internal or configuration error detected, module is not functional
gsm_bus_error - module detected a number of communication errors, but it is still working
gsm_connected - module connected to GSM network (domestic or roaming)
gsm_roaming - domestic network not found, roaming connected
gsm_gprs_connected - module connected to GPRS network
S
St ta at tu us s w wo or rd ds s
gsm_error_status - module status: b7:voice_tx_error, b6:SMS_tx_error, b5:udp_tx_error, b4:no_credit,
b3:config_error, b2:PIN_error, b1:sim_error, b0:network_denied
gsm_gprs_status - status of GPRS network registration (0..7-connecting, 8-connected, 9..11-error)
M
Mo od du ul le e i in nf fo o
gsm_signal_quality - GSM signal quality, range 0..31 (0..7 poor, 8..14 acceptable, 14..31 good)
gsm_credit_balance - credit balance in local currency for prepaid SIM card (e.g. 24 means 24EUR), checked
every 60min, always zero for postpaid.
I
In nc co om mi in ng g v vo oi ic ce e c ca al ll l a an nd d S SM MS S
gsm_incoming_call - incoming call active, 1-ringing, 0-hangup
gsm_incoming_rings - number of incoming rings, reset when receiving a call, counting up with each ring
gsm_incoming_digit_req - set to read a single digit of incoming phone number, will reset automatically
gsm_incoming_digit_data - single number of incoming phone number
gsm_message_received - incoming message received (1-message received)
gsm_incoming_letter_req - set to read a single letter of incoming sms message, will reset automatically.
gsm_incoming_letter_data - single letter of incoming sms message
O
Ou ut tg go oi in ng g v vo oi ic ce e c ca al ll l a an nd d S SM MS S
gsm_outgoing_digit_data - single digit of phone number to write to module
gsm_outgoing_digit_req - set to write a single digit of outgoing phone to module buffer, will reset automatically
gsm_outgoing_digit_ack - acknowledge on outgoing number digit
gsm_outgoing_index - index of phone number to be called; -1 for number from cybro-defined, 0 for first
number in the [OutgoingPhones] list, 1 for 2nd, 2 for 3rd...
gsm_outgoing_call_req - set to make an outgoing voice call; phone will ring until call is denied, or for
maximum of 60 seconds, will reset automatically
gsm_outgoing_letter_data - single letter of sms message to write to module
gsm_outgoing_letter_req - set to write a single character of outgoing sms message to module buffer, will reset
automatically
gsm_outgoing_letter_ack - acknowledge on outgoing message letter
gsm_outgoing_sms_req - set to send custom defined sms message, will reset automatically
P
Pu us sh h m me es ss sa ag ge e
gsm_push_message_req - request to send push message