gsm

README

gsm

A high level Go driver for GSM modems.

The gsm package provides a wrapper around at that supports sending and receiving SMS messages, including long multi-part messages.

Features

Supports the following functionality:

• Simple synchronous interface for sending messages
• Both text and PDU mode interface to GSM modem
• Asynchronous handling of received messages

Usage

Construction

The GSM modem is constructed with New:

modem := gsm.New(atmodem)

Some modem behaviour can be controlled using optional parameters. This example sets the puts the modem into PDU mode:

modem := gsm.New(atmodem, gsm.WithPDUMode)

Modem Init

The modem is reset into a known state and checked that is supports GSM functionality using the Init method:

err := modem.Init()

The Init method is a wrapper around the at Init method, and accepts the same options:

err := modem.Init(at.WithCmds("Z","^CURC=0"))

Sending Short Messages

Send a simple short message that will fit within a single SMS TPDU using SendShortMessage:

mr, err := modem.SendShortMessage("+12345","hello")

The modem may be in either text or PDU mode.

Sending Long Messages

This example sends an SMS with the modem in text mode:

mrs, err := modem.SendLongMessage("+12345", apotentiallylongmessage)

Sending PDUs

Arbitrary SMS TPDUs can be sent using the SendPDU method:

mr, err := modem.SendPDU(tpdu)

Receiving Messages

A handler can be provided for received SMS messages using StartMessageRx:

handler := func(msg gsm.Message) {
    // handle message here
}
err := modem.StartMessageRx(handler)

The handler can be removed using StopMessageRx:

modem.StopMessageRx()

Options

A number of the modem methods accept optional parameters. The following table comprises a list of the available options:

Option	Method	Description
WithCollector(Collector)	StartMessageRx	Provide a custom collector to reassemble multi-part SMSs.
WithEncoderOption(sms.EncoderOption)	New	Specify options for encoding outgoing messages.
WithPDUMode	New	Configure the modem into PDU mode (default).
WithReassemblyTimeout(time.Duration)	StartMessageRx	Overrides the time allowed to wait for all the parts of a multi-part message to be received and reassembled. The default is 24 hours. This option is ignored if WithCollector is also applied.
WithSCA(pdumode.SMSCAddress)	New	Override the SCA when sending messages.
WithTextMode	New	Configure the modem into text mode. This is only required to send short messages in text mode, and conflicts with sending long messages or PDUs, as well as receiving messages.

Documentation

Overview

Package gsm provides a driver for GSM modems.

Index

• Variables
• func UnmarshalTPDU(info []string) (tp tpdu.TPDU, err error)
• type Collector
• type ErrCollect
  • func (e ErrCollect) Error() string
• type ErrDecode
  • func (e ErrDecode) Error() string
• type ErrReassemblyTimeout
  • func (e ErrReassemblyTimeout) Error() string
• type ErrUnmarshal
  • func (e ErrUnmarshal) Error() string
• type ErrorHandler
• type GSM
  • func New(a *at.AT, options ...Option) *GSM
  • func (g *GSM) Init(ctx context.Context, options ...at.InitOption) (err error)
  • func (g *GSM) SendLongMessage(ctx context.Context, number string, message string, ...) (rsp []string, err error)
  • func (g *GSM) SendPDU(ctx context.Context, tpdu []byte, options ...at.CommandOption) (rsp string, err error)
  • func (g *GSM) SendShortMessage(ctx context.Context, number string, message string, ...) (rsp string, err error)
  • func (g *GSM) StartMessageRx(ctx context.Context, mh MessageHandler, eh ErrorHandler, options ...RxOption) error
  • func (g *GSM) StopMessageRx(ctx context.Context)
• type Message
• type MessageHandler
• type Option
  • func WithEncoderOption(eo sms.EncoderOption) Option
  • func WithSCA(sca pdumode.SMSCAddress) Option
• type RxOption
  • func WithCollector(c Collector) RxOption
  • func WithInitCmds(c ...string) RxOption
  • func WithReassemblyTimeout(d time.Duration) RxOption

Variables

var (
	// ErrMalformedResponse indicates the modem returned a badly formed
	// response.
	ErrMalformedResponse = errors.New("modem returned malformed response")

	// ErrNotGSMCapable indicates that the modem does not support the GSM
	// command set, as determined from the GCAP response.
	ErrNotGSMCapable = errors.New("modem is not GSM capable")

	// ErrNotPINReady indicates the modem SIM card is not ready to perform
	// operations.
	ErrNotPINReady = errors.New("modem is not PIN Ready")

	// ErrOverlength indicates the message is too long for a single PDU and
	// must be split into multiple PDUs.
	ErrOverlength = errors.New("message too long for one SMS")

	// ErrUnderlength indicates that two few lines of info were provided to
	// decode a PDU.
	ErrUnderlength = errors.New("insufficient info")

	// ErrWrongMode indicates the GSM modem is operating in the wrong mode and
	// so cannot support the command.
	ErrWrongMode = errors.New("modem is in the wrong mode")
)

var WithPDUMode = pduModeOption(true)

WithPDUMode specifies that the modem is to be used in PDU mode.

This is the default mode.

var WithTextMode = pduModeOption(false)

WithTextMode specifies that the modem is to be used in text mode.

This overrides is the default PDU mode.

Functions

func UnmarshalTPDU

func UnmarshalTPDU(info []string) (tp tpdu.TPDU, err error)

UnmarshalTPDU converts +CMT info into the corresponding SMS TPDU.

Types

type Collector

type Collector interface {
	Collect(tpdu.TPDU) ([]*tpdu.TPDU, error)
}

Collector is the interface required to collect and reassemble TPDUs.

By default, this is implemented by an sms.Collector.

type ErrCollect

type ErrCollect struct {
	TPDU tpdu.TPDU
	Err  error
}

ErrCollect indicates that an error occured that prevented the TPDU from being collected.

func (ErrCollect) Error

func (e ErrCollect) Error() string

type ErrDecode

type ErrDecode struct {
	TPDUs []*tpdu.TPDU
	Err   error
}

ErrDecode indicates that an error occured that prevented the TPDUs from being cdecoded.

func (ErrDecode) Error

func (e ErrDecode) Error() string

type ErrReassemblyTimeout

type ErrReassemblyTimeout struct {
	TPDUs []*tpdu.TPDU
}

ErrReassemblyTimeout indicates that one or more segments of a long message are missing, preventing the complete message being reassembled.

The missing segments are the nil entries in the array.

func (ErrReassemblyTimeout) Error

func (e ErrReassemblyTimeout) Error() string

type ErrUnmarshal

type ErrUnmarshal struct {
	Info []string
	Err  error
}

ErrUnmarshal indicates an error occured while trying to unmarshal the TPDU received from the modem.

func (ErrUnmarshal) Error

func (e ErrUnmarshal) Error() string

type ErrorHandler

type ErrorHandler func(error)

ErrorHandler receives asynchronous errors.

type GSM

type GSM struct {
	*at.AT
	// contains filtered or unexported fields
}

GSM modem decorates the AT modem with GSM specific functionality.

func New

func New(a *at.AT, options ...Option) *GSM

New creates a new GSM modem.

func (*GSM) Init

func (g *GSM) Init(ctx context.Context, options ...at.InitOption) (err error)

Init initialises the GSM modem.

func (*GSM) SendLongMessage

func (g *GSM) SendLongMessage(ctx context.Context, number string, message string, options ...at.CommandOption) (rsp []string, err error)

SendLongMessage sends an SMS message to the number.

The modem must be in PDU mode. The message is split into concatenated SMS PDUs, if necessary.

The mr of send PDUs is returned on success, else an error.

func (*GSM) SendPDU

func (g *GSM) SendPDU(ctx context.Context, tpdu []byte, options ...at.CommandOption) (rsp string, err error)

SendPDU sends an SMS PDU.

tpdu is the binary TPDU to be sent. The mr is returned on success, else an error.

func (*GSM) SendShortMessage

func (g *GSM) SendShortMessage(ctx context.Context, number string, message string, options ...at.CommandOption) (rsp string, err error)

SendShortMessage sends an SMS message to the number.

If the modem is in PDU mode then the message is converted to a single SMS PDU.

The mr is returned on success, else an error.

func (*GSM) StartMessageRx

func (g *GSM) StartMessageRx(ctx context.Context, mh MessageHandler, eh ErrorHandler, options ...RxOption) error

StartMessageRx sets up the modem to receive SMS messages and pass them to the message handler.

The message may have been concatenated over several SMS PDUs, but if so is reassembled into a complete message before being passed to the message handler.

Errors detected while receiving messages are passed to the error handler.

Requires the modem to be in PDU mode.

func (*GSM) StopMessageRx

func (g *GSM) StopMessageRx(ctx context.Context)

StopMessageRx ends the reception of messages started by StartMessageRx,

type Message

type Message struct {
	Number  string
	Message string
	SCTS    tpdu.Timestamp
	TPDUs   []*tpdu.TPDU
}

Message encapsulates the details of a received message.

The message is composed of one or more SMS-DELIVER TPDUs.

Commonly required fields are extracted for easy access.

type MessageHandler

type MessageHandler func(Message)

MessageHandler receives a decoded SMS message from the modem.

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option is a construction option for the GSM.

func WithEncoderOption

func WithEncoderOption(eo sms.EncoderOption) Option

WithEncoderOption applies the encoder option when converting from text messages to SMS TPDUs.

func WithSCA

func WithSCA(sca pdumode.SMSCAddress) Option

WithSCA sets the SCA used when transmitting SMSs in PDU mode.

This overrides the default set in the SIM.

The SCA is only relevant in PDU mode, so this option also enables PDU mode.

type RxOption

type RxOption interface {
	// contains filtered or unexported methods
}

RxOption is a construction option for the GSM.

func WithCollector

func WithCollector(c Collector) RxOption

WithCollector overrides the collector to be used to reassemble long messages.

The default is an sms.Collector.

func WithInitCmds

func WithInitCmds(c ...string) RxOption

WithInitCmds overrides the commands required to setup the modem to notify when SMSs are received.

The default is {"+CSMS=1","+CNMI=1,2,0,0,0"}

func WithReassemblyTimeout

func WithReassemblyTimeout(d time.Duration) RxOption

WithReassemblyTimeout specifies the maximum time allowed for all segments in a long message to be received.

The default is 24 hours.

This option is overridden by WithCollector.