sierracns.1

.TH sierracns 1
'''
.SH NAME
sierracns \- Control and Status (CnS) protocol tool for Sierra Wireless 3G/4G modems.
'''
.SH SYNOPSIS
\fBsierracns\fR [\fIoptions\fR] [\fIoid oid oid\fR ...]
.br
\fBsierracns\fR [\fIoptions\fR] \fIcommand\fR [\fRarg\fR ...]
'''
.SH DESCRIPTION
sierracns sends and recieves CnS packets to Sierra devices.

Sierra Wireless 3G modems handled by sierra.ko kernel driver provide three
TTY devices, typically named ttyUSB0, ttyUSB1 and ttyUSB2.
The 1st port (ttyUSB0) provides Hayes modem interface (AT commands, PPP).
The 3rd port (ttyUSB2) is GPS NMEA output.

CnS is the protocol these modems talk on their 2nd tty interface. 

CnS allows querying runtime status data from the modem without interrupting
PPP connection on the 1st port, as well as doing some configuration like setting
modem internal time, managing phonebook on GSM units and so on.

\fBsierracns\fR allows sending/receiving CnS requests and provides limited
decoding for some of modem replies.
'''
.SH USAGE
Each CnS request carries a 2-byte code (object id, oid) which determines what is being
requested. Modem replies with some binary data, which the user is expected to decode.

Requests can be either get, set, or notification control. Get and notifications
generally require only the oid. For set requests, the data to be set should also be provided.

The tool sends specified requests, and waits for the modem to reply. Replies the tool
can decode are shown in human-readable form; any other replies are dumped raw.
'''
.SS Options
.IP "\fB-d\fR \fIdevice\fR"
Device to use, something like /dev/ttyUSB1.
.IP \fB-C\fR
Dump raw CnS packets.
.IP \fB-H\fR
Dump raw HIP packets.
.IP \fB-O\fR
Dump outgoing packets too (without this option, only incoming packets are shown).
.IP \fB-n\fR
Show notification enable/disable packets (normally suppressed).
.P
'''
.SS OID requests
The basic way of communicating with the modem. Each [oid] chunk represents a single CnS packet,
encoded this way:
.IP "NNNN[o[PPPP....]]" 10
.P
where NNNN is the oid (hexadecimal, 4 digits), o is operation and PPPP... is payload.
Possible operations are get ":", set "=", enable notifications "+", disable notifications "-".
Bare oid means empty get request. Payload is a sequence of hex byte value,
like 23 or 7F, possibly separated with dashes for readability.
.P
Examples:
.IP "0003"
Simple GET request, no payload.
.IP "1044:0001"
GET request with payload.
.IP "0F02=0001-0001-00FF-FFFFFFF0"
SET request with payload (start GPS fix in this case)
.IP "1001+"
Enable notification request, no payload.
'''
.P
Some OIDs the tool can decode:
.PD 0
.RS
.TP
0001 Firmware version
.TP
0002 Firmware build date
.TP
0003 Hardware version
.TP
0004 Boot version
.TP
000A Model
.TP
1000 ESN [CDMA]
.TP
1001 RSSI (received signal strength indicator)
.TP
1004 IMSI (network name) [UMTS]
.TP
1006 Service indication [CDMA]
.TP
001B Network date and time [UMTS]
.TP
1032 Network date and time [CDMA]
.TP
1065 RSSI and Ec/io [CDMA]
.TP
1067 IMEI [UMTS]
.TP
1069 HDR Service Indication [CDMA]
.TP
106A HDR Hybrid Mode [CDMA]
.TP
4003 Cell location [CDMA?]
.RE
'''
.SS Commands
These are mostly shorthands for common OIDs and OID sequences, including those
for which payload is non-trivial or hard to write manually.
'''
.sp
.IP "\fBrssi\fR" 4
Signal strength.
.IP "\fBhdr\fR\ \ " 4
Signal strength, Ec/io and connection mode for CDMA modems.
.IP "\fBwatch\fR [\fIoid oid oid ...\fR]" 4
Enable notifications and show notification packets for specified oids.
With no oids specified, show all incoming notification.
.IP "\fBunwatch\fR [\fIoid oid oid ...\fR]" 4
Disable notifications for specified oids. With no oids, listen for incoming
notification and disable them (useful for recovering after Sierra Watcher).
.IP "\fBwatch\fR \fBrssi\fR|\fBhdr\fR"
Same as watch 1001 and watch 1065 respectively.
.IP "\fBreset\fR" 4
Modem reset.
.IP "\fBtime\fR" 4
Show current network time.
.IP "\fBradio\fR [\fBon\fR|\fBoff\fR]" 4
Enable/disable radio. Another name for "radio off" is airplane mode.
.IP "\fBgps\fR\ " 4
Show current GPS location.
.IP "\fBgps\fR on\fR|\fBoff\fR" 4
Same as AT!GPSLOCK=0|1
.IP "\fBgps fix\fR [\fB-m \fImode\fR] [\fB-t \fIduration\fR] [\fB-d \fIaccuracy\fR] [\fB-\fR]" 4
Initiate GPS fix. Same as AT!GPSFIX=mode,duration,accuracy.
With trailing -, wait for results and report coordinates.
.IP "\fBgps track\fR [\fB-m \fImode\fR] [\fB-t \fIduration\fR] [\fB-d \fIuncert\fR] [\fB-n \fInfixes\fR] [\fB-i \fIinterval\fR]" 4
Start GPS tracking session. Same as AT!GPSTRACK=mode,duration,accuracy,nfixes,interval.
.IP "\fBgps end\fR" 4
End GPS tracking session.
.IP "\fBgps status\fR"
Show GPS status. Same as AT!GPSSTATUS.
.IP "\fBgps satellites\fR"
List of visible satellites.
.IP "\fBgps clear\fR" 4
Clear internal GPS data (almanac, ephemeris etc).
'''
.sp
.P
Use -CO or read the sources to see which OIDs are being requested by each command.

.SH NOTES
The tool is experimental. Use with caution.
CnS protocol is considered proprietary, documentation is scarce and unreliable.

OIDs and reply formats may be different for different modems.
In particular, CDMA and GSM/UMTS modems may return different data for the same oids.
Reply format for some oids depends on firmware version.
Whenever possible, try to obtain documentation for your particular modem.

The tool may return bogus results; if unsure, dump raw CnS data (-C)
and try to decode it yourself.

GET requests should be harmless (but that's not guaranteed).
SET requests, on the other hand, should be used with care.
However, if documentation is to be trusted, you are risking nvram at most.
Writing to flash (firmware) area requires packets not implemented in this tool.

.SH AUTHOR
Alex Suykov <alex.suykov@gmail.com>
.br
See https://github.com/arsv/sierracns for the source

.SH SEE ALSO
Sierra document 2131024 "CDMA 1xEV-DO CnS Reference".