Usage of chan_dongle

Module management in Asterisk

For manual management of module you can use the following commands in asterisk CLI:

  • module load chan_dongle.so
    Load module into Asterisk. Config is read from /path_to_asterisk_config/dongle.conf
  • module unload chan_dongle.so
    Unload module from Asterisk. All modems are de-attached
  • module reload chan_dongle.so
    Reload configuration from config file. If any change is done since last load, then it will be applied now. It is exactly that dongle reload gracefully

chan_dongle CLI commands

chan_dongle provides the following CLI commands:

  • dongle cmd
    Send to the rfcomm port on the device with the specified
  • dongle reset
    Send reboot command to modem 
    AT+CFUN=1,1
  • dongle stop gracefully
    Stop gracefully. Prevents new incoming and outgoing calls and SMS and outgoing USSD from starting up, but allows calls/SMS/USSD in progress to continue. When all the calls/SMS/USSD have finished, stops
  • dongle stop now
    Stop now. Stops immediately, ending any calls/SMS/USSD in progress
  • dongle stop when convenient
    Stop when convenient. Waits until has no calls/SMS/USSD in progress, and then it stops . It does not prevent new calls/SMS/USSD from entering the .
  • dongle show device settings
    Shows settings for
  • dongle show device state
    Shows detailed state for
  • dongle show device statistics
    Shows statistics for
  • dongle show devices
    Shows summarized state for all devices
  • dongle show version
    Show module version
  • dongle sms
    Send SMS to with the using
  • dongle pdu
    Send PDU using
  • dongle ussd
    Send USSD command using
  • dongle start
    Start if not removed from before.
  • dongle restart gracefully
    Prevents new incoming and outgoing calls and SMS and outgoing USSD from starting up in , but allows calls/SMS/USSD in progress to continue. When call/SMS/USSD has finished, restarts. Restart mean first stop device and second reopen and initialize.
  • dongle restart now
    Restarts immediately, ending any calls/SMS/USSD in progress.
  • dongle restart when convenient
    Waits until has no calls/SMS/USSD in progress, and then it restarts . It does not prevent new calls/SMS/USSD from entering the .
  • dongle remove gracefully
    Prevents new incoming and outgoing calls and SMS and outgoing USSD from starting up in , but allows calls/SMS/USSD in progress to continue. When call/SMS/USSD has finished, stopping and removed from module.
  • dongle remove now
    Remove from Asterisk immediately.
  • dongle remove when convenient
    Waits until has no calls/SMS/USSD in progress and then remove . It does not prevent new calls/SMS/USSD from entering the .
  • dongle reload gracefully
    Reloads the chan_dongle configuration gracefully
  • dongle reload now
    Reloads the chan_dongle configuration now
  • dongle reload when convenient
    Reloads the chan_dongle configuration when convenient. BUG: complete removed devices from dongle.conf not removed from module after reload. Use disable=yes as workaround.

Dialplan applications

The following applications are provided by chan_dongle:

  • DongleStatus(, )
  • DongleSendSMS(, [,Message [, Validity [, Report]]])

Dialplan function

The following functions are provided by chan_dongle:

CHANNEL(callstate)

when reading may has values

  • active
  • held
  • dialing
  • alerting
  • incoming
  • waiting
  • initialize
  • released
  • unknown

for example, you can separate incoming calls from waiting:

[dongle-incoming]
exten => s,1,GotoIf($["${CHANNEL(callstate)}" = "waiting"]?waiting-call)

Also, you can assign to this functions too, but this useful only when callstate changed from 'held' to 'active' and mean put on held other calls on this device and activate call linked with current asterisk channel. For example

exten => s,n,Set(CHANNEL(callstate)=active)

But remember that putting on hold GSM calls, does not cause termination or freeze dialplan execution for linked asterisk channels.

Channel variables

For each asterisk's channel created by chan_dongle (both incoming and outgoing legs) next channel variables are set

  • DONGLENAME

name of device name

  • DONGLEPROVIDER

same as 'Provider Name' column of 'dongle show devices' CLI command

  • DONGLEIMEI

same as 'IMEI' column of 'dongle show devices' CLI command

  • DONGLEIMSI

same as 'IMSI' column of 'dongle show devices' CLI command

  • DONGLENUMBER

same as 'Number' column of 'dongle show devices' CLI command

For 'ussd' extension of incoming context next channel variables are set

  • USSD_TYPE

numberic type of USSD Response from 0 till 5

  • USSD_TYPE_STR

textual type of USSD Response one from 'USSD Notify', 'USSD Request', 'USSD Terminated by network', 'Other local client has responded', 'Operation not supported', 'Network time out'

  • USSD

Content of USSD Response

  • USSD_BASE64

Content of USSD Response encoded to Base64, useful when USSD is multiline

For 'sms' extension of incoming context next channel variables are set

  • SMS

Content of SMS

  • SMS_BASE64

Content of SMS encoded to Base64, useful when SMS is multiline

  • CMGR

Raw CMGR response from dongle

  • TOA

Type Of Address of SMS originator see also ${CALLERID(num)}

Incoming calls

On incoming call, chan_dongle tries to find matching exten in defined context (see dongle.conf). There is 3 different exten to search, in the following order:

  • Subscriber Number stored in SIM.
  • Number defined in variable exten in dongle.conf
  • s exten

To save Subscriber Number, you can write an entry for OWN NUMBERS storage on SIM. For example, in asterisk CLI

dongle cmd dongle0 AT+CPBS=\"ON\"
dongle cmd dongle0 AT+CPBW=1,\"+79139131234\",145

After restarting dongle0, incoming calls will start dialplan from exten

exten => +79139131234,1,Noop()

also variable CALLERID(dnid) will be set to +79139131234

If subscriber number is unknown, then you can set this in in dongle.conf

exten = +79139131234

If subscriber number is unknown and there is no exten entry in dongle.conf, then s exten will be used as starting point in dialpan.

Receive SMS and USSD

You can handle received SMS and USSD using sms and ussd exten, respectively.

Example for received sms

[dongle-incoming-sms]
exten => sms,1,Noop(Incoming SMS from ${CALLERID(num)} ${BASE64_DECODE(${SMS_BASE64})})
exten => sms,n,System(echo '${STRFTIME(${EPOCH},,%Y-%m-%d %H:%M:%S)} - ${DONGLENAME} - ${CALLERID(num)}: ${BASE64_DECODE(${SMS_BASE64})}' >> /var/log/asterisk/sms.txt)
exten => sms,n,Hangup()

Example for received USSD

[dongle-incoming-ussd]
exten => ussd,1,Noop(Incoming USSD: ${BASE64_DECODE(${USSD_BASE64})})
exten => ussd,n,System(echo '${STRFTIME(${EPOCH},,%Y-%m-%d %H:%M:%S)} - ${DONGLENAME}: ${BASE64_DECODE(${USSD_BASE64})}' >> /var/log/asterisk/ussd.txt)
exten => ussd,n,Hangup()

Also note, execution of this exten takes place in a “Local” channel.

Always define sms and ussd extens for context where you handle incoming calls for dongle device! Otherwise, incoming SMS or USSD can execute extensions for voice call with unpredictable results.

[dongle-incoming]
include => dongle-incoming-sms
include => dongle-incoming-ussd

Also note that h exten is executed for SMS/USSD just before Local channel is destroyed.

Manager commands

Chan_dongle can provide the following manager commands:

  • DongleShowDevices
  • DongleSendUSSD
  • DongleSendSMS
  • DongleSendPDU
  • DongleSetCCWA
  • DongleReset
  • DongleRestart
  • DongleStop
  • DongleStart
  • DongleRemove
  • DongleReload

Manager Events

Chan_dongle generates the following manager events:

  • DongleDeviceEntry
  • DongleShowDevicesComplete
  • DongleUSSDStatus
  • DongleSMSStatus
  • DongleNewCUSD
  • DongleNewUSSD
  • DongleNewUSSDBase64
  • DongleCEND
  • DongleCallStateChange
  • DongleStatus
  • DongleNewCMGR
  • DongleNewSMS
  • DongleNewSMSBase64
  • DonglePortFail

Console AT commands

You can send AT commands to any modem using

CLI>dongle cmd  

Some useful AT commands:

AT command Description
AT+CCWA=0,0,1 disable call-waiting
AT+CFUN=1,1 reboot modem
AT^CARDLOCK=“ send unlock code
AT^SYSCFG=13,0,3FFFFFFF,0,3 modem 2G only, automatic search any band, no roaming
AT^SYSCFG=2,0,3FFFFFFF,2,4 Any
AT^SYSCFG=13,1,3FFFFFFF,2,4 2G only
AT^SYSCFG=14,2,3FFFFFFF,2,4 3G only
AT^SYSCFG=2,1,3FFFFFFF,2,4 2G preferred
AT^SYSCFG=2,2,3FFFFFFF,2,4 3G preferred
AT^U2DIAG=0 enable modem function only
ATI get relevant information from modem
ATZ reset modem configuration
AT+CIMI read IMSI
AT+CLCK=“SC”,0,“ disable PIN verification