The SMS driver allows the Weble universal gateway to send and receive SMS text messages for alerts, notifications, and remote control. It supports two sending methods that can be used independently or combined for redundancy:
- WebleSMS: sends SMS through the Weble cloud SMS web service. Requires a WebleSMS account (username/password). Supports groups and diffusion lists managed in the cloud.
- Local Modem: sends and receives SMS using a physical SIM modem connected to the gateway. Supports receiving incoming messages (inbox) and PDU mode for extended character sets.
Both methods can be combined with automatic failover:
WebleSMS > LocalModem— tries WebleSMS first, falls back to the local modem if the cloud service fails.LocalModem > WebleSMS— tries the local modem first, falls back to WebleSMS if the modem fails.
¶ 1. Getting started
¶ 1.1 Gateway configuration
Create a new gateway and select the SMS driver. Choose the Type based on your setup:
- WebleSMS — cloud-based SMS sending via the Weble web service. Configure Username and Password with your WebleSMS account credentials.
- LocalModem — SMS sending/receiving via a physical SIM modem connected to the gateway (USB or serial). Configure PDU mode and SMSC Address if needed.
- WebleSMS > LocalModem — redundancy mode: tries WebleSMS first, falls back to local modem.
- LocalModem > WebleSMS — redundancy mode: tries local modem first, falls back to WebleSMS.
¶ 1.2 Sending an SMS
Once the gateway is started, insert a new address with the recipient's phone number:
- Create an address with the destination phone number (e.g.
%sms:+41791234567). - Write a text value to this address — the value becomes the SMS message body.
The SMS is sent immediately using the configured provider.
¶ 1.3 Using with routes
Like the SMTP driver, the SMS driver is typically used as a destination in routes for sending alert notifications. For example, a route can monitor a sensor value and send an SMS when a threshold is exceeded.
¶ 1.4 Receiving SMS (Local Modem only)
When using the LocalModem type, incoming SMS messages are automatically received and stored as addresses in the Messages receive tab. Each received message creates an address with the message text as its value. The special address %sms:lastMessage always contains the most recently received message.
¶ 2. Gateway parameters
¶ 2.1 General parameters
| Label | JSON Key | Description |
|---|---|---|
| Name | name | A descriptive name for this SMS gateway instance. |
| Cluster ID | cluster | Cluster identifier (integer). Use 0 for single-gateway setups. |
| Description | description | Optional description for this gateway. |
| Type | type | Sending method: WebleSMS (cloud service), LocalModem (SIM modem), WebleSMS > LocalModem (cloud first, modem fallback), or LocalModem > WebleSMS (modem first, cloud fallback). |
| Save outbox | saveOutboxMessages | If enabled, sent messages are recorded as addresses in the Messages sended tab with their delivery status (sent, error, message ID). |
¶ 2.2 WebleSMS parameters
These parameters are only visible when the Type includes WebleSMS.
| Label | JSON Key | Description |
|---|---|---|
| Username | username | WebleSMS account username. |
| Password | password | WebleSMS account password. |
| Default CLIP | defaultSubject | Default Caller Line Identification (CLIP) — the sender name or number displayed on the recipient's phone. |
¶ 2.3 Local Modem parameters
These parameters are only visible when the Type includes LocalModem.
| Label | JSON Key | Description |
|---|---|---|
| PDU mode | pduMode | Enable PDU (Protocol Data Unit) mode for SMS encoding. PDU mode supports extended character sets (Unicode) and longer messages. Default: enabled. |
| SMSC Address | SMSCAddress | The Short Message Service Center address. Usually auto-detected by the SIM card. Only set this if the modem requires a specific SMSC address. |
¶ 2.4 Gateway JSON examples
WebleSMS:
{
"type": "WebleSMS",
"username": "myaccount",
"password": "mypassword",
"defaultSubject": "WebleGateway",
"saveOutboxMessages": false
}
Local Modem:
{
"type": "LocalModem",
"pduMode": true,
"SMSCAddress": "",
"saveOutboxMessages": true
}
Redundancy (cloud first, modem fallback):
{
"type": "WebleSMS > LocalModem",
"username": "myaccount",
"password": "mypassword",
"defaultSubject": "WebleGateway",
"pduMode": true,
"SMSCAddress": "",
"saveOutboxMessages": true
}
¶ 3. Addresses
¶ 3.1 Address format
SMS addresses use the prefix %sms: followed by a destination and optionally a CLIP (sender identifier):
%sms:[clip@]destination
Where:
- clip (optional) — the Caller Line Identification sent with the SMS (only with WebleSMS). Use
@to separate the CLIP from the destination. - destination — a phone number (e.g.
+41791234567) or, with WebleSMS, a group/diffusion alias.
¶ Examples
| Address | CLIP | Destination |
|---|---|---|
%sms:+41791234567 |
default | +41791234567 |
%sms:Alert@+41791234567 |
Alert | +41791234567 |
%sms:MyGateway@+33612345678 |
MyGateway | +33612345678 |
¶ 3.2 Address tabs
The SMS driver organizes addresses into multiple tabs:
| Tab | Description |
|---|---|
| Single destinations | Manually created addresses for sending SMS to individual phone numbers. |
| Messages receive | (Local Modem only) Automatically created addresses for received SMS messages. Read-only. |
| Messages sended | (when Save outbox is enabled) Log of sent messages with delivery status, destination, CLIP, message content, and send date. Read-only. |
| Groups | (WebleSMS only) Addresses linked to WebleSMS contact groups. Send one SMS to a group to reach all members. |
| Diffusions | (WebleSMS only) Addresses linked to WebleSMS diffusion lists for mass messaging. |
¶ 3.3 Address parameters
| Label | JSON Key | Description |
|---|---|---|
| Name | name | The SMS address in the format described above. |
| Description | description | Optional description for this address. |
| Log | log | Logging mode: never, on update, always, or a duration in milliseconds. |
¶ 3.4 Sending messages (writing values)
Writing a value to an SMS address triggers an SMS. The value can be:
Simple text:
"Temperature alert: Room 1 is at 35°C"
JSON object with additional options:
{
"text": "Temperature alert: Room 1 is at 35°C",
"type": 0
}
¶ 3.5 Special addresses
| Address | Description |
|---|---|
%sms:lastMessage |
(Local Modem only) Always contains the text of the last received SMS message. |
%sms:outbox-<n> |
(when Save outbox is enabled) Sent message log entry with delivery status. |
¶ 5. Developer reference
| Property | Value |
|---|---|
| Address regex | %sms: prefix |
| Readable | No |
| Writable | Yes (validated by parseName) |
| Auto-creation | Yes — writing to a new address creates it |
¶ Address parsing
Format: %sms:[clip@]destination
// Simple phone number
writeValue('%sms:+41791234567', 'Alert message')
// With CLIP (sender ID)
writeValue('%sms:MyGateway@+41791234567', 'Alert message')
¶ Write value format
String — sent as SMS text:
writeValue('%sms:+41791234567', 'Temperature is 35°C')
Object — additional SMS options:
writeValue('%sms:+41791234567', {
text: 'Temperature is 35°C',
type: 0, // SMS type
encoding: '16bit' // character encoding
})
¶ Notes
exports.retryDelay = 120000(2 minutes before retry on driver error)- Redundancy: providers are tried in order (e.g.
WebleSMS > LocalModem) - Incoming SMS (Local Modem) create numbered addresses
%sms:1,%sms:2, etc. %sms:lastMessagealways contains the latest received SMS