openHAB

This page is part of archived documentation for openHAB 4.1. Go to the current stable version

# SMSModem Binding

This binding connects to a USB serial GSM modem (or a network exposed one, see ser2net) and allows openHAB to send and receive SMS through it.

Serial modem should all use the same communication protocol (AT message) and therefore this binding should be compatible with every dongle. However, there is a gap between theory and reality and success may vary. The protocol stack is based on the no longer supported smslib project (more precisely a v4 fork), and all modems supported by this library should be OK.

The following devices have been reported functional :

  • Huawei E180

# Supported Things

Two things are supported by this binding :

  • A smsmodembridge, representing the dongle connected on the local computer
  • A smsmodemremotebridge, representing the dongle exposed over the network (with ser2net or other similar software)
  • A smsconversation, representing a conversation between one distant msisdn and the msisdn on the sim card in the dongle.

# Discovery

There is no discovery process for smsmodembridge or smsmodemremotebridge thing. A smsconversation thing will be discovered and added to the inbox everytime the modem should receive a SMS by a new sender.

# Thing Configuration

The smsmodembridge or smsmodemremotebridge things requires at least two parameters to work properly.

For local smsmodembridge:

Parameter Name type direct serial modem
serialPort text The serial port to access (eg. /dev/tty/USBx)
baud integer Baud rate

For remote smsmodemremotebridge:

Parameter Name type serial over network
ip text IP address of the computer hosting the ser2net service
networkPort integer The network port of the ser2net service

The other parameters are optional :

Parameter Name type description
simPin text If your sim card is protected, fill this field with the PIN code
pollingInterval integer Delay between two checks for new message (in seconds)
delayBetweenSend integer Delay to wait between two messages post (in milliseconds, could be necessary for slow modem)

The smsconversation thing is just a shortcut to address/receive messages with a specific msisdn. It is not mandatory to use the binding, as you can use action and trigger channel to send/receive a message once the smsmodem bridge is configured.

Parameter Name type description
recipient text The msisdn of the phone you want to discuss with.
deliveryReport boolean If enabled, ask the network for a delivery report (default false)
encoding text The encoding to use when sending the message (either Enc7, Enc8, EncUcs2, EncCustom, default is Enc7). EncUcs2 is good for non latin character, but SMS character size limit is then reduced

# Channels

The smsconversation supports the following channels :

channel type description
receive String The last message received
send String A message to send
deliverystatus String Delivery status (either UNKNOWN, QUEUED, SENT, PENDING, DELIVERED, EXPIRED, or FAILED). Several status are only possible if the delivery report parameter is enabled

# Trigger channels

The smsmodembridge and smsmodemremotebridge has the following trigger channel :

Channel ID event
receivetrigger The msisdn and message received (concatened with the '|' character as a separator)

# Rule action

This binding includes a rule action to send SMS.

(Rule DSL)
val smsAction = getActions("smsmodem","smsmodem:smsmodembridge:<uid>")

(javascript JSR)
var smsAction = actions.get("smsmodem","smsmodem:smsmodembridge:<uid>");

Where uid is the Bridge UID of the smsmodembridge thing.

Once this action instance is retrieved, you can invoke the 'send' method on it:

smsAction.sendSMS("1234567890", "Hello world!")

Or with a special encoding:

smsAction.sendSMS("1234567890", "Hello world!", "EncUcs2")

# Full Example

# Thing configuration

things/smsmodem.things:

Bridge smsmodem:smsmodembridge:adonglename "USB 3G Dongle " [ serialPort="/dev/ttyUSB0", baud="19200" ] {
    Thing smsconversation aconversationname [ recipient="XXXXXXXXXXX", deliveryReport="true" ]
}

# Send SMS

sms.rules for DSL:

rule "Alarm by SMS"
when
   Item Alarm changed
then
   val smsAction = getActions("smsmodem","smsmodem:smsmodembridge:dongleuid")
   smsAction.sendSMS("33123456789", "Alert !")
end

# Receive and forward SMS

sms.py with the python helper library :

@rule("smscommand.receive", description="Receive SMS and resend it")
@when("Channel smsmodem:smsmodembridge:dongleuid:receivetrigger triggered")
def smscommand(event):
    sender_and_message = event.event.split("|")
    sender = sender_and_message[0]
    content = sender_and_message[1]
    actions.get("smsmodem", "smsmodem:smsmodembridge:dongleuid").send("336123456789", sender + " just send the following message: " + content)
Caught a mistake or want to contribute to the documentation? Edit this page on GitHub (opens new window)

← SNCF →