Difference between revisions of "GSM"
(Created page with "This I/O Server provides services for sending and receiving SMSs and events generation for incoming calls via serial GSM modem. The employed protocol complies with the AT com...") |
|||
(37 intermediate revisions by 5 users not shown) | |||
Line 1: | Line 1: | ||
− | This I/O Server provides services for sending and receiving SMSs and events generation for incoming calls via | + | This I/O Server provides services for sending and receiving SMSs and events generation for incoming calls via GSM modem. |
− | The employed protocol complies with the AT commands set specified by the GSM standard set. It has been tested on the GenPro 16e and GenPro 18e modems by Erco&Gener | + | The employed protocol complies with the AT commands set specified by the GSM standard set. It has been tested on the following modems: |
+ | |||
+ | * GenPro 16e and GenPro 18e modems by Erco&Gener | ||
+ | * AirLink FXT009 modem by Sierra Wireless | ||
+ | * RB800/RB900 series modems by Teleorigin | ||
[[Category:I/O Server]] | [[Category:I/O Server]] | ||
+ | |||
== Communication == | == Communication == | ||
Line 14: | Line 19: | ||
| 9600 (GenPro modems) | | 9600 (GenPro modems) | ||
|- | |- | ||
− | | 115200 (default on | + | | 115200 (default setting on other modems) |
|- | |- | ||
| '''Data bits''' | | '''Data bits''' | ||
Line 30: | Line 35: | ||
== HSYCO Configuration == | == HSYCO Configuration == | ||
+ | Add a GSM I/O Server in the [[Settings#I/O Servers|I/O Servers section of the Settings]] and set its parameters: | ||
+ | |||
+ | === Communication === | ||
+ | *'''Comm ID''': select the comm port the device is connected to. | ||
+ | |||
+ | === High Availability === | ||
+ | *'''Shutdown when inactive''': defaults to true. | ||
=== Options === | === Options === | ||
Line 75: | Line 87: | ||
| | | | ||
|<number> | |<number> | ||
− | |phone number of the SMS service center (use the international format, e.g. +393492000200). If not specified, the default number saved on the SIM card will be used. If not available, the driver will not be able to | + | |phone number of the SMS service center (use the international format, e.g. +393492000200). If not specified, the default number saved on the SIM card will be used. If not available, the driver will not be able to send SMS messages |
|- | |- | ||
Line 83: | Line 95: | ||
|n ≥ 0 | |n ≥ 0 | ||
|number of sending attempts on an outgoing SMS in case of error | |number of sending attempts on an outgoing SMS in case of error | ||
+ | |||
+ | |- | ||
+ | |||
+ | |rowspan="2"|simphase2 | ||
+ | |rowspan="2"|false | ||
+ | |true | ||
+ | |enable SIM phase 2+ compatibility | ||
+ | |- | ||
+ | |false | ||
+ | |default | ||
|} | |} | ||
Line 117: | Line 139: | ||
|- | |- | ||
− | |rowspan=" | + | |rowspan="4"|call |
− | |<num> | + | |rowspan="2"|<num> |
|R | |R | ||
|incoming call from number <num><sup>[[#note2|[Note 2]]]</sup> in progress. An event is generated for each “ring” during the call | |incoming call from number <num><sup>[[#note2|[Note 2]]]</sup> in progress. An event is generated for each “ring” during the call | ||
+ | |- | ||
+ | |W | ||
+ | |start a voice call to number <num><sup>[[#note2|[Note 1]]]</sup> | ||
+ | |- | ||
+ | |end | ||
+ | |W | ||
+ | |end the ongoing voice call | ||
|- | |- | ||
|unknown | |unknown | ||
|R | |R | ||
|incoming call from an unknown number in progress | |incoming call from an unknown number in progress | ||
+ | |||
+ | |- | ||
+ | |||
+ | |rowspan="7"|call.state | ||
+ | |start | ||
+ | |R | ||
+ | |a voice call has been started | ||
+ | |- | ||
+ | |alerting | ||
+ | |R | ||
+ | |the ongoing voice call is in the alerting state, i.e. the phone on the other end is ringing | ||
+ | |- | ||
+ | |active | ||
+ | |R | ||
+ | |the ongoing voice call is active, i.e. the call has been answered from the other end | ||
+ | |- | ||
+ | |held | ||
+ | |R | ||
+ | |the ongoing voice call is being held | ||
+ | |- | ||
+ | |dialling | ||
+ | |R | ||
+ | |the modem is dialling the number | ||
+ | |- | ||
+ | |waiting | ||
+ | |R | ||
+ | |the ongoing voice call is waiting | ||
+ | |- | ||
+ | |end | ||
+ | |R | ||
+ | |the voice call has ended | ||
|- | |- | ||
Line 165: | Line 225: | ||
== User Interface == | == User Interface == | ||
− | === | + | === SMS Object === |
− | {{: | + | {{:SMS_(UI Object)}} |
=== UISET Actions === | === UISET Actions === | ||
Line 176: | Line 236: | ||
!colspan="2"|Set to | !colspan="2"|Set to | ||
|- | |- | ||
− | | | + | |
− | | | + | |inbox |
− | |colspan="2"|latest | + | |value |
+ | |colspan="2"|latest incoming SMS messages (as many as specified by the 'inboxsize' option) | ||
+ | |||
|- | |- | ||
− | | | + | |
− | | | + | |rowspan="2"|connection.label.online |
− | | | + | |rowspan="2"|visible |
+ | |true | ||
+ | |when datapoint connection = online | ||
|- | |- | ||
− | | | + | |false |
− | | | + | |when datapoint connection = offline |
− | + | ||
|- | |- | ||
− | |rowspan="2"|connection.label | + | |
+ | |rowspan="2"|connection.label.offline | ||
|rowspan="2"|visible | |rowspan="2"|visible | ||
|true | |true | ||
Line 195: | Line 260: | ||
|false | |false | ||
|when datapoint connection = online | |when datapoint connection = online | ||
+ | |||
|- | |- | ||
− | |rowspan="2"| | + | |
+ | |rowspan="2"|signal.label.0 | ||
|rowspan="2"|visible | |rowspan="2"|visible | ||
|true | |true | ||
− | |when | + | |when the GSM signal level is equal to 0 |
|- | |- | ||
|false | |false | ||
− | |when | + | |when the GSM signal level is not 0 |
+ | |||
|- | |- | ||
− | |rowspan="2"| | + | |
+ | |rowspan="2"|signal.label.1 | ||
|rowspan="2"|visible | |rowspan="2"|visible | ||
|true | |true | ||
− | |when | + | |when the GSM signal level is between 1 and 8 |
|- | |- | ||
|false | |false | ||
− | |when | + | |when the GSM signal level is not between 1 and 8 |
− | |||
− | + | |- | |
− | + | |rowspan="2"|signal.label.2 | |
− | + | |rowspan="2"|visible | |
− | + | |true | |
− | + | |when the GSM signal level is between 9 and 16 | |
+ | |- | ||
+ | |false | ||
+ | |when the GSM signal level is not between 9 and 16 | ||
|- | |- | ||
− | |rowspan="2" | | + | |rowspan="2"|signal.label.3 |
− | | | + | |rowspan="2"|visible |
− | | | + | |true |
+ | |when the GSM signal level is between 17 and 24 | ||
|- | |- | ||
− | | | + | |false |
− | | | + | |when the GSM signal level is not between 17 and 24 |
|- | |- | ||
− | |rowspan="2" | | + | |rowspan="2"|signal.label.4 |
− | | | + | |rowspan="2"|visible |
− | | | + | |true |
+ | |when the GSM signal level is above 24 | ||
|- | |- | ||
− | | | + | |false |
− | | | + | |when the GSM signal level is below 25 |
|- | |- | ||
− | |rowspan="2" | | + | |rowspan="2"|signal.label.unknown |
− | | | + | |rowspan="2"|visible |
− | | | + | |true |
+ | |when the GSM signal level is unknown | ||
|- | |- | ||
− | | | + | |false |
− | | | + | |when the GSM signal level is known |
|- | |- | ||
− | |rowspan="2" | | + | |rowspan="2"|sending.label |
− | | | + | |rowspan="2"|visible |
− | | | + | |true |
+ | |when the modem is sending a message | ||
|- | |- | ||
− | | | + | |false |
− | | | + | |when the modem is not sending a message |
|- | |- | ||
− | |rowspan="2" | | + | |rowspan="2"|error.label |
− | | | + | |rowspan="2"|visible<br />blink |
− | | | + | |true |
+ | |for 5 seconds after there’s been an error sending a message | ||
|- | |- | ||
− | | | + | |false |
− | | | + | |default value |
+ | |} | ||
+ | |||
+ | === USER Commands === | ||
+ | {| class="wikitable" | ||
+ | !UI Object | ||
+ | !ID | ||
|- | |- | ||
+ | |[[input]] | ||
+ | |<ioserver_id>.sms.number | ||
+ | |- | ||
+ | |[[input]] | ||
+ | |<ioserver_id>.sms.text | ||
+ | |- | ||
+ | |[[submit]] | ||
+ | |<ioserver_id>.sms.send | ||
+ | |} | ||
+ | |||
+ | From the resulting interface, digit the addressee number (or comma-separated list of numbers) in the input field with ID “<ioserver_id>.sms.number” and the body text in the input field “<ioserver_id>.sms.text”, then press the submit button. | ||
+ | |||
+ | N.B. If the option 'countrycode' is used, then the country code will be automatically added to the numbers, unless the latter begins with a '+'. | ||
+ | For instance, assuming the value of the option 'countrycode' is set to “39”, the addressee number “3480077000” will be automatically changed to “+393480077000”, while the number “+46765007700” will remain unchanged. | ||
+ | If, on the other hand, no default country code has been specified, then the addressee numbers must always be provided prepending the country code. | ||
+ | |||
+ | == PUK-locked SIM == | ||
+ | In case the SIM card used for the GSM modem is PUK-locked, it is required to provide the PUK code and a new PIN to set on the SIM card. To this end, create in the root folder of HSYCO a file named “<ioserver_id>.puk”, where <ioserver_id> is the ID of the corresponding I/O Server (e.g. “gsm.puk”). In this file add a single line containing the PUK code and the new PIN code separated by a comma, for instance: | ||
+ | <pre> | ||
+ | 12345678,1234 | ||
+ | </pre> | ||
+ | The file will be automatically deleted after it has been used by the I/O Server. | ||
+ | |||
+ | == Examples == | ||
+ | === Sending an SMS === | ||
+ | Assuming that we are sending an SMS at 12 o' clock to number 777123456 located in Italy (International prefix code: +39) and the option "countrycode" of the GSM IO server is not specified, this is the corresponding EVENTS programming declaration: | ||
+ | |||
+ | time = 1200 : io gsm.sms.+39777123456 = "I'm sending an sms to the world" | ||
+ | |||
+ | You can send multiple SMSs to different numbers using this syntax: | ||
+ | |||
+ | time = 1200 : io gsm.sms.+39777123456 gsm.sms.+39777654321 = "I'm sending an sms to the world" | ||
− | + | === Receiving an SMS === | |
− | + | Hsyco can receive SMSs through the GSM IO server and perform actions according to the text contained in the SMS. | |
− | |||
− | + | io gsm.sms.777123456 = "Help" : io gsm.sms.777123456 = "I accept the following commands: Open, Status" | |
+ | io gsm.sms.777123456 = "Open" : io knx.1/1/2 = 1, wait = 1, io knx.1/1/2 = 0 | ||
+ | |||
+ | == Release Notes == | ||
+ | === 3.6.0 === | ||
+ | * new "simphase2" option to enable support for SIM phase 2+ on some modems | ||
+ | * bug fix: fixed hang on high traffic conditions | ||
+ | |||
+ | === 3.5.0 === | ||
+ | *added voice call functionality | ||
+ | *improved stability for Teleorigin modem | ||
+ | |||
+ | === 3.4.0 === | ||
+ | *fixed bug occurring when sending messages containing the '=' character | ||
+ | *minor fixes to the sms UI object | ||
+ | === 3.3.0 === | ||
+ | *added “resend” server option | ||
+ | *improved AT commands compatibility | ||
+ | *added PUK-unlock functionality | ||
+ | === 3.2.1 === | ||
+ | *added “srvc” server option | ||
+ | *bug fix: user.IOStartupEvent() was not called at startup | ||
+ | === 3.1.0 === | ||
+ | *initial release | ||
+ | |||
+ | ---- | ||
+ | |||
+ | |||
+ | ''GenPro 16e, GenPro 18e, and Erco&Gener are registered trademarks of Erco&Gener.'' |
Latest revision as of 15:17, 17 February 2017
This I/O Server provides services for sending and receiving SMSs and events generation for incoming calls via GSM modem.
The employed protocol complies with the AT commands set specified by the GSM standard set. It has been tested on the following modems:
- GenPro 16e and GenPro 18e modems by Erco&Gener
- AirLink FXT009 modem by Sierra Wireless
- RB800/RB900 series modems by Teleorigin
Contents
Communication
Employ a RS-232 straight cable to connect the modem directly to HSYCO or to an Ethernet/RS-232 gateway.
RS-232 parameters:
Baud rate | 9600 (GenPro modems) |
115200 (default setting on other modems) | |
Data bits | 8 |
Stop bit | 1 |
Parity | none |
Flow control | RTS/CTS |
HSYCO Configuration
Add a GSM I/O Server in the I/O Servers section of the Settings and set its parameters:
Communication
- Comm ID: select the comm port the device is connected to.
High Availability
- Shutdown when inactive: defaults to true.
Options
ID | Default | Values | Description |
---|---|---|---|
pin | <code> | 4-digits PIN code of the SIM card (if used) | |
gui | true | true | enable support for the UI object, UISET actions and USER commands |
false | disable UI support | ||
inboxsize | 10 | n ≥ 0 | the number of incoming messages to display in the UI object |
countrycode | <code> | the default country code (e.g. “39”, for Italy) to be used when not otherwise specified. If omitted all provided numbers shall include the country code
| |
srvc | <number> | phone number of the SMS service center (use the international format, e.g. +393492000200). If not specified, the default number saved on the SIM card will be used. If not available, the driver will not be able to send SMS messages | |
resend | 4 | n ≥ 0 | number of sending attempts on an outgoing SMS in case of error |
simphase2 | false | true | enable SIM phase 2+ compatibility |
false | default |
Datapoints
ID | Value | R/W | Description |
---|---|---|---|
connection | online | R | connection established |
offline | R | HSYCO can't connect to the modem | |
sms.<num> | <text> | R | an SMS message has been received form the number <num>[Note 2] with <text> as body |
W | send an SMS message to the number <num>[Note 1] with <text> as body | ||
call | <num> | R | incoming call from number <num>[Note 2] in progress. An event is generated for each “ring” during the call |
W | start a voice call to number <num>[Note 1] | ||
end | W | end the ongoing voice call | |
unknown | R | incoming call from an unknown number in progress | |
call.state | start | R | a voice call has been started |
alerting | R | the ongoing voice call is in the alerting state, i.e. the phone on the other end is ringing | |
active | R | the ongoing voice call is active, i.e. the call has been answered from the other end | |
held | R | the ongoing voice call is being held | |
dialling | R | the modem is dialling the number | |
waiting | R | the ongoing voice call is waiting | |
end | R | the voice call has ended | |
sms.<num>.sent | <mr> | R | a message has been successfully sent to the number <num> and the message reference number is <mr> |
sms.<num>.errors | <val> | R | an error occurred while sending a message to number <num>. The value <val> is an increasing counter of the occurred errors since the I/O Server started |
signal | {0 ... 31} | R | the GSM signal level has the reported value (ranging from 0 to 31) |
unknown | R | the GSM signal level is unknown |
- Note 1
- If the option 'countrycode' is used, then the country code will be automatically added to the specified numbers, unless the latter begins with a '+' character. For instance, assuming the option 'countrycode' is set to “39”, the addressee number “3480077000” will be automatically changed to “+393480077000”, while the number “+46765007700” will remain unchanged. If, on the other hand, no default country code has been specified, then the addressee numbers must always be provided prepending the country code.
- Note 2
- The numbers are reported as sent from the modem and the format may vary depending on the number itself and the modem settings. If the reported number is an international number, then a '+' will be prepended to it, unless the country code is equal to the value of the 'countrycode' option. In the last case the country code will be omitted. In some cases, the sender number field might also be replaced by an alphanumeric string.
User Interface
SMS Object
The user interface for sending SMS messages:
The SMS object is listed in the Project Editor’s new object list only when at least one GSM I/O Server is defined.
Parameters
- server id: the server ID
- position: the object's position. Use the pixels or rows and columns coordinates format
Syntax
(sms <server id>; <position>)
E.g.
(sms serverid; x10y20)
UISET Actions
ID | Attribute | Set to | |
---|---|---|---|
inbox | value | latest incoming SMS messages (as many as specified by the 'inboxsize' option) | |
connection.label.online | visible | true | when datapoint connection = online |
false | when datapoint connection = offline | ||
connection.label.offline | visible | true | when datapoint connection = offline |
false | when datapoint connection = online | ||
signal.label.0 | visible | true | when the GSM signal level is equal to 0 |
false | when the GSM signal level is not 0 | ||
signal.label.1 | visible | true | when the GSM signal level is between 1 and 8 |
false | when the GSM signal level is not between 1 and 8 | ||
signal.label.2 | visible | true | when the GSM signal level is between 9 and 16 |
false | when the GSM signal level is not between 9 and 16 | ||
signal.label.3 | visible | true | when the GSM signal level is between 17 and 24 |
false | when the GSM signal level is not between 17 and 24 | ||
signal.label.4 | visible | true | when the GSM signal level is above 24 |
false | when the GSM signal level is below 25 | ||
signal.label.unknown | visible | true | when the GSM signal level is unknown |
false | when the GSM signal level is known | ||
sending.label | visible | true | when the modem is sending a message |
false | when the modem is not sending a message | ||
error.label | visible blink |
true | for 5 seconds after there’s been an error sending a message |
false | default value |
USER Commands
UI Object | ID |
---|---|
input | <ioserver_id>.sms.number |
input | <ioserver_id>.sms.text |
submit | <ioserver_id>.sms.send |
From the resulting interface, digit the addressee number (or comma-separated list of numbers) in the input field with ID “<ioserver_id>.sms.number” and the body text in the input field “<ioserver_id>.sms.text”, then press the submit button.
N.B. If the option 'countrycode' is used, then the country code will be automatically added to the numbers, unless the latter begins with a '+'. For instance, assuming the value of the option 'countrycode' is set to “39”, the addressee number “3480077000” will be automatically changed to “+393480077000”, while the number “+46765007700” will remain unchanged. If, on the other hand, no default country code has been specified, then the addressee numbers must always be provided prepending the country code.
PUK-locked SIM
In case the SIM card used for the GSM modem is PUK-locked, it is required to provide the PUK code and a new PIN to set on the SIM card. To this end, create in the root folder of HSYCO a file named “<ioserver_id>.puk”, where <ioserver_id> is the ID of the corresponding I/O Server (e.g. “gsm.puk”). In this file add a single line containing the PUK code and the new PIN code separated by a comma, for instance:
12345678,1234
The file will be automatically deleted after it has been used by the I/O Server.
Examples
Sending an SMS
Assuming that we are sending an SMS at 12 o' clock to number 777123456 located in Italy (International prefix code: +39) and the option "countrycode" of the GSM IO server is not specified, this is the corresponding EVENTS programming declaration:
time = 1200 : io gsm.sms.+39777123456 = "I'm sending an sms to the world"
You can send multiple SMSs to different numbers using this syntax:
time = 1200 : io gsm.sms.+39777123456 gsm.sms.+39777654321 = "I'm sending an sms to the world"
Receiving an SMS
Hsyco can receive SMSs through the GSM IO server and perform actions according to the text contained in the SMS.
io gsm.sms.777123456 = "Help" : io gsm.sms.777123456 = "I accept the following commands: Open, Status" io gsm.sms.777123456 = "Open" : io knx.1/1/2 = 1, wait = 1, io knx.1/1/2 = 0
Release Notes
3.6.0
- new "simphase2" option to enable support for SIM phase 2+ on some modems
- bug fix: fixed hang on high traffic conditions
3.5.0
- added voice call functionality
- improved stability for Teleorigin modem
3.4.0
- fixed bug occurring when sending messages containing the '=' character
- minor fixes to the sms UI object
3.3.0
- added “resend” server option
- improved AT commands compatibility
- added PUK-unlock functionality
3.2.1
- added “srvc” server option
- bug fix: user.IOStartupEvent() was not called at startup
3.1.0
- initial release
GenPro 16e, GenPro 18e, and Erco&Gener are registered trademarks of Erco&Gener.