at

README

AT command library

This is a work in progress. Use at your own risk

The AT command library is a Go library for communicating with mobile network IoT modules via their AT command set. Currently only the uBlox Sara N210/N211 is supported, but this library might work with the uBlox N310 too.

As mentioned above this is a work in progress so expect things to change around and maintainance of this library to be somewhat episodic.

If you want to contribute or you have suggestions, please do not hesitate to contact @borud.

Sample code

package main

import (
	"log"
	"os"

	"github.com/lab5e/at/n211"
)

const baudRate = 9600

func main() {
	if len(os.Args) < 2 {
		log.Fatalf("Usage %s <serial device>", os.Args[0])
	}

	device := n211.New(os.Args[1], baudRate)
	if err := device.Start(); err != nil {
		log.Fatalf("Error opening device: %v", err)
	}
	defer device.Close()

	// Turn on debugging so you can see the interaction with the device
	device.SetDebug(true)

	// Just send a blank AT command to verify the device is there
	if err := device.AT(); err != nil {
		log.Fatalf("Error speaking to device on '%s': %v", os.Args[1], err)
	}
	log.Printf("Device seems to be responsive")
}

Documentation

Overview

Package at implements a simple interface to communicate with mobile IoT modules. For now we only have support for one family of modules (the uBlox SARA N2 and possibly N3 modules), but we might add support for more modules in the future.

Example of how to connect to a device:

import "github.com/lab5e/at/n211"

...

device := n211.New(serialPort, baudRate)
if err := device.Start(); err != nil {
    log.Fatalf("Error opening device: %v", err)
}

Please refer to the Device interface to see what methods are available.

Index

• Constants
• Variables
• func TrimQuotes(s string) string
• type APN
• type CommandInterface
  • func NewCommandInterface(device string, baudRate int) *CommandInterface
  • func (c *CommandInterface) AddErrorOutput(newError string)
  • func (c *CommandInterface) AddSplitChars(newSplit string)
  • func (c *CommandInterface) AddSuccessOutput(newSuccess string)
  • func (c *CommandInterface) Close()
  • func (c *CommandInterface) SendCRLF(s string)
  • func (c *CommandInterface) SetDebug(debug bool)
  • func (c *CommandInterface) Start() error
  • func (c *CommandInterface) Transact(s string, fn func(string) error) error
• type DefaultImplementation
  • func (d *DefaultImplementation) AT() error
  • func (d *DefaultImplementation) Close()
  • func (d *DefaultImplementation) GetAPN() (*APN, error)
  • func (d *DefaultImplementation) GetAddr() (int, string, error)
  • func (d *DefaultImplementation) GetIMEI() (string, error)
  • func (d *DefaultImplementation) GetIMSI() (string, error)
  • func (d *DefaultImplementation) SetAPN(apn string) error
  • func (d *DefaultImplementation) SetDebug(debug bool)
  • func (d *DefaultImplementation) SetRadio(on bool) error
  • func (d *DefaultImplementation) Start() error
• type Device
• type ReceivedData
• type Stats

Constants

const DefaultLineTimeout = 5 * time.Second

Variables

var (
	// IMSIRegex is a regexp that matches an IMSI number
	IMSIRegex = regexp.MustCompile("([0-9]{5,15})")

	// IMEIRegex is a regexp that matches an IMEI number
	IMEIRegex = regexp.MustCompile(`\+CGSN: ([0-9]{5,15})`)

	// CCIDRegex is a regexp that matches an CCID
	CCIDRegex = regexp.MustCompile(`\+CCID: ([0-9]{5,15})`)
)

var (
	// ErrReadTimeout read from device timed out
	ErrReadTimeout = errors.New("read timed out")

	// ErrATError ...
	ErrATError = errors.New("device returned ERROR")
)

Functions

func TrimQuotes

func TrimQuotes(s string) string

Types

type APN

type APN struct {
	ContextIdentifier int
	PDPType           string
	Name              string
	Address           string
}

APN contains data about the APN. We have skipped the optional fields to simplify matters.

type CommandInterface

type CommandInterface struct {
	// contains filtered or unexported fields
}

CommandInterface is a helper type for modems. It's optional to use it when implementing support for new modules but quite helpful.

func NewCommandInterface

func NewCommandInterface(device string, baudRate int) *CommandInterface

func (*CommandInterface) AddErrorOutput

func (c *CommandInterface) AddErrorOutput(newError string)

Some modems (hello BG95) sends additional text strings when a command completes with an error

func (*CommandInterface) AddSplitChars

func (c *CommandInterface) AddSplitChars(newSplit string)

Add a command split character or set of characters. Since some modems (hello BG95) changes its behaviour in certain comamnds the CRLF sequence isn't always emitted when the modem is ready to accept new characters.

func (*CommandInterface) AddSuccessOutput

func (c *CommandInterface) AddSuccessOutput(newSuccess string)

Some modems (hello BG95) sends additional text string when a command completes successful.

func (*CommandInterface) Close

func (c *CommandInterface) Close()

func (*CommandInterface) SendCRLF

func (c *CommandInterface) SendCRLF(s string)

func (*CommandInterface) SetDebug

func (c *CommandInterface) SetDebug(debug bool)

func (*CommandInterface) Start

func (c *CommandInterface) Start() error

func (*CommandInterface) Transact

func (c *CommandInterface) Transact(s string, fn func(string) error) error

transact drains the output from the device, then sends the string appending CRLF to the device, then it reads the response and calls fn with each line in the response as long as fn returns ErrContinueReading.

type DefaultImplementation

type DefaultImplementation struct {
	Cmd *CommandInterface
}

DefeaultImplementation is a default implementation

func (*DefaultImplementation) AT

func (d *DefaultImplementation) AT() error

func (*DefaultImplementation) Close

func (d *DefaultImplementation) Close()

func (*DefaultImplementation) GetAPN

func (d *DefaultImplementation) GetAPN() (*APN, error)

func (*DefaultImplementation) GetAddr

func (d *DefaultImplementation) GetAddr() (int, string, error)

func (*DefaultImplementation) GetIMEI

func (d *DefaultImplementation) GetIMEI() (string, error)

func (*DefaultImplementation) GetIMSI

func (d *DefaultImplementation) GetIMSI() (string, error)

func (*DefaultImplementation) SetAPN

func (d *DefaultImplementation) SetAPN(apn string) error

func (*DefaultImplementation) SetDebug

func (d *DefaultImplementation) SetDebug(debug bool)

func (*DefaultImplementation) SetRadio

func (d *DefaultImplementation) SetRadio(on bool) error

func (*DefaultImplementation) Start

func (d *DefaultImplementation) Start() error

type Device

type Device interface {

	// Start opens the serial port and starts the reader goroutine
	Start() error

	// Close the serial port
	Close()

	// SetDebug turns on debugging if debug is true
	SetDebug(debug bool)

	AT() error

	// GetIMSI reads the IMSI from the device
	GetIMSI() (string, error)

	// GetIMEI reads the IMEI from the device
	GetIMEI() (string, error)

	// GetCCID returns the CCID of the SIM
	GetCCID() (string, error)

	// SetAPN sets the APN.  Be aware that this operation performs
	// multiple transactions and reboots the device.
	SetAPN(apn string) error

	// GetAPN returns the current APN settings
	GetAPN() (*APN, error)

	// GetAddr returns the context identifier (CID) and address
	// currently allocated to the device. This (usually) invokes the AT+CGPADDR command.
	GetAddr() (int, string, error)

	// SetRadio turns the radio on if on is true and off is on is false. This (usually) invokes the AT+CFUN
	// command
	SetRadio(bool) error

	// CreateUDPSocket creates an UDP socket. If the port is non-zero,
	// receiving is enabled and +NSONMI URCs will appear for any
	// message that is received on that port.
	CreateUDPSocket(port int) (int, error)

	// SendUDP sends an UDP packet using a previously opened socket.
	// Returns number of bytes written and whether or not there was an
	// error.
	SendUDP(socket int, address net.IP, remotePort int, data []byte) (int, error)

	// ReceiveUDP data on a socket. When data arrives a +NSONMI URC will
	// be issued indicating the socket the message was received on and the
	// amount of data.
	//
	// This command takes a length, which is the maximum amount of data
	// that will be returned. If the requested length is larger than the
	// actual size of the returned data, only the length of returned data
	// is provided, and the remaining length is returned as 0.
	//
	// If the requested length is less than the amount of data returned,
	// only the requested amount of data will be returned, plus an
	// indication of the number of bytes remaining. Once a message has
	// been fully read, a new +NSONMI URC will be sent if there is another
	// message to process.
	ReceiveUDP(socket int, length int) (*ReceivedData, error)

	// CloseUDPSocket - Close the specified socket. The pending messages
	// to be read (if present) will be dropped. No further +NSONMI URCs
	// will be generated. If the socket has already been closed, or was
	// never created, an error result code will be issued.
	CloseUDPSocket(socket int) error
}

Device is a generic interface for mobile network devices with AT command interfaces.

type ReceivedData

type ReceivedData struct {
	Socket    int
	IP        string
	Port      int
	Length    int
	Data      []byte
	Remaining int
}

ReceivedData contains the data received from an UDP connection

type Stats

type Stats struct {
	SignalPower int
	//  total power within receive bandwidth expressed in tenth of dBm
	TotalPower int
	// TX power expressed in tenth of dBm
	TXPower int
	// elapsed TX time since last power on event expressed in milliseconds
	TXTime int
	// elapsed RX time since last power on event expressed in milliseconds
	RXTime int
	// physical ID of the cell providing service to the module
	CellID int
	// TODO(borud): document
	ECL int
	//  last SNR value expressed in tenth of dB
	SNR int
	// TODO(borud): document
	EARFCN int
	// TODO(borud): document
	PCI int
	//  last RSRQ value expressed in tenth of dB
	RSRQ int
}

Stats contains basic operational statistics