Welcome to Sitch Sensor’s documentation!

Version 3.7.3

Sensor Environment Variables

The SITCH Sensor requires some environment variables to be set in order to operate.

Environment Variable	Purpose
CGI_WHITELIST	List of trusted CGIs.
FEED_RADIO_TARGETS	(Optional) Radio types to target for feed ingestion. Defaults to GSM.
FEED_URL_BASE	Base URL for Sensor feed.
GSM_MODEM_BAND	Restrict GSM modem to this band. Options: (EGSM_MODE | PGSM_MODE | DCS_MODE | GSM850_MODE | PCS_MODE | EGSM_DCS_MODE | GSM850_PCS_MODE | EGSM_PCS_MODE | ALL_BAND)
GSM_MODEM_PORT	(Optional) Set the tty for the GSM modem
KAL_BAND	Band for Kalibrate to scan. (GSM850 | GSM-R | GSM900 | EGSM | DCS | PCS)
KAL_GAIN	Gain value for Kalibrate. Try 60.
KAL_THRESHOLD	Alarm threshold for Kalibrate channel power level. Try 1000000.
LOCATION_NAME	Name of the location for this sensor. No spaces.
LOG_HOST	Logstash endpoint. Formatted like this: hostname:port
MCC_LIST	List of Mobile Country Codes to ingest from feed. USA is 310, 311, 312, 313, and 316 List is comma-separated: “310,311,316”
MODE	Set to “clutch” to go into a wait loop during start. Useful for troubleshooting.
NO_FEED_UPDATE	(Optional) If set, do not attempt to update the feed on boot.
STATE_LIST	Comma-separated list of states for feed ingestion. California and Texas would be: “CA,TX”
VAULT_PATH	Path to Logstash/Filebeat credentials in Vault. In the demo environment, this is ‘secret/client’
VAULT_TOKEN	Client token used to retrieve credentials from Vault.
VAULT_URL	URL for Vault instance containing Logstash/Filebeat credentials. Looks like: “https://ser.ver.com:8200”
NO_FEED_UPDATE	If set, do not attempt to update the feed on boot.
GSM_MODEM_PORT	(Optional) GSM modem USB-TTY port. This should be autodetected and not need to be set. Looks like: /dev/ttyUSB0 See: “Found but undetected TTY ” in the docs
GPS_DEVICE_PORT	(Optional) GPS device USB-TTY port. This should be autodetected and not need to be set. Looks like: /dev/ttyUSB0 See: “Found but undetected TTY ” in the docs

Understanding the Log Data Collected by Sitch

The following sections describe the data for the files found in ‘/data/sitch/log/’.

cells.log

<cell>

possible values	description
0	The serving cell
1-6	The index of the neighboring cell

<arfcn>

[Absolute radio frequency channel number](https://en.wikipedia.org/wiki/Absolute_radio-frequency_channel_number)

<rxl>

Receive level

The measured signal level shall be mapped to an RXLEV value between 0 and 63, as follows:

possible values	description
0	less than -110 dBm.
1	-110 dBm to -109 dBm.
2	-109 dBm to -108 dBm.
…
…
62	-49 dBm to -48 dBm.
63	greater than -48 dBm.

<rxq>

Receive quality

possible values	description
0…7	as [RXQUAL](https://en.wikipedia.org/wiki/Rxqual) values
99	not known or not detectable

<mcc>

[Mobile country code](https://en.wikipedia.org/wiki/Mobile_country_code)

<mnc>

[Mobile network code](https://en.wikipedia.org/wiki/Mobile_country_code)

<bsic>

[Base station identity code](https://en.wikipedia.org/wiki/Base_station_identity_code)

<cellid>

[Cell id](https://en.wikipedia.org/wiki/Cell_ID)

NOTE: In a 7-item line, cellid is not provided. We set it to 0 to prevent barfing elsewhere.

<lac>

[Location area code](http://www.telecomabc.com/l/lac.html)

<rla>

Receive level access minimum

GUESS: Minimum receiving level permitted to access the system Per: similar AT engineering mode (AT+QENG) command in [M95 AT commands manual](http://eddywireless.com/yahoo_site_admin/assets/docs/M95_AT_Commands_Manual_V12.196112248.pdf)

<txp>

Transmit power maximum CCCH

<TA>

[Timing Advance](https://en.wikipedia.org/wiki/Timing_advance)

Sensor Troubleshooting

GSM modem device detection

If you’re using a GSM modem that’s not recognized by the device detector, please add the output from running the ATI command against your GSM modem in the variable named positive_match in the is_a_gsm_modem() method, in the sensor/sitch/sitchlib/device_detector.py file. Then send a pull request so that everyone can get the benefit of your discovery.

You can do this using the resin.io terminal on the device by doing the following steps.

1. Set the environment variable ‘GSM_MODEM_BAND’ to ‘nope’ to disable the scanner.
2. Identify which TTY port your device is running on. You can find this in the startup logs under the string ‘DeviceDetector: Detected USB devices’.
3. Run python from the sensors virtual environment

/app/sitch/venv/bin/python

4. Create a serial connection to the GSM modem.

> import serial
> port = '/dev/[THE_MODEMS_TTY_SYS_NAME]'
> serconn = serial.Serial(port, 4800, timeout=1)

5. Run the following snippet to get the string you need.

> test_command = "ATI \r\n"
> serconn.flush()
> for i in xrange(10):
> line = None
> line = serconn.readline()
> if line is None:
>     time.sleep(1)
>     pass
> else:
>     print("Use this GSM Modem String in your pull request: {0}".format(line))
> serconn.flush()
> serconn.close()

Found but undetected TTY

“The DeviceDetector shows it found my GSM Modem or GPS Device by the Configurator does not detect it”

How to identify if this is your issue

You will be able to recognize this issue if three conditions are met.

1. You are receiving an error that the device is not configured or cannot bind to its socket.

2. Your Configurator returns an empty array instead of a USB-TTY device name when it attempts to detect a device.

3. Your device detector is detecting these devices

If the device detector cannot find the devices, as the following log message shows, then this is not your issue.

How to fix this issue

To fix this issue you can set the hard-coded environment variable for the device that is not detected.

In the following example the GSM modem is not detected.

> 22.04.17 08:53:27 (-0400) Configurator: Detected GSM modems:
> 22.04.17 08:53:27 (-0400) []
> 22.04.17 08:53:27 (-0400) Configurator: Detected GPS devices:
> 22.04.17 08:53:27 (-0400) [u'/dev/ttyUSB0']

This shows me that the GSM modem was not detected and that my GPS device can be found at ‘/dev/ttyUSB0’.

By looking at my DeviceDetector I can see that I have two USB devices connected. It also gives me the ‘sys_name’ of each device.

Since I know that my GPS device has a sys_name of ‘ttyUSB0’ I know that the sys_name GSM device is ‘ttyUSB1’.

I can now set the ‘GSM_MODEM_PORT’ environment variable to point to /dev/ttyUSB1 in the resin.io “Environment Variables’ interface.

(NOTE: for those unfamiliar with python strings it should be noted that the ‘u’ in front of each quoted value in these example logs is specifying that the string is a Unicode string. You do not want to enter the ‘u’ in front of /dev/ttyUSB1 when setting your environment variables.)

If you have successfully set the environment variable you will no longer receive an error message.

In the case of the GSM modem you will also see that the following message has replaced the original error.

SITCH Sensor Internal API

AlertManager

class sitchlib.AlertManager(device_id)

AlertManager is used to ensure alerts are consistently formatted.

build_alert(alert_id, alert_message)

Build the actual alert and returns it, formatted.

Parameters:

• alert_id (int) – The ID of the alert you want to build
• alert_message (str) – The message to be embedded in the alert.

Returns:

Position 0 contains the string ‘sitch_alert’. Position 1

contains the alert and metadata.

Return type:

tuple

get_alert_type(alert_id)

Return the alert description for alert_id.

ArfcnCorrelator

class sitchlib.ArfcnCorrelator(states, feed_dir, whitelist, power_threshold, device_id)

The ArfcnCorrelator compares ARFCN metadata against feeds and threshold.

The feed data is put in place by the FeedManager class, prior to instantiating the ArfcnCorrelator.

classmethod arfcn_from_scan(scan_type, scan_doc)

Pull the ARFCN from different scan types.

Parameters:

• scan_type (str) – “kal_channel”, “gsm_modem_channel”, or “gps”.
• scan_doc (dict) – Scan document

Returns:

ARFCN from scan, or None if scan is unrecognized or

unsupported.

Return type:

str

arfcn_over_threshold(arfcn_power)

Compare the ARFCN power against the thresholdset on instantiation.

Parameters:arfcn_power (float) – If this isn’t a float already, it will be coerced to float. Returns:True if arfcn_power is over threshold, False if not. Return type:bool

classmethod assemble_gps(item)

Assemble lat/lon into a format we can work with.

classmethod assemble_latlon(item)

Assemble feed lat/lon into a haversine-parseable format.

compare_arfcn_to_feed(arfcn)

Wrap other functions that dig into the FCC license DB.

This relies on the observed_arfcn instance variable for caching, to skip DB comparison, that way we (probably) won’t end up with a forever-increasing queue size.

Parameters:arfcn (str) – This is the text representation of the ARFCN we want to compare against the FCC license database. Returns:

You get back a list of alerts as tuples, where position 0 is

’sitch_alert’ and position 1 is the actual alert.

Return type:list

correlate(scan_bolus)

Entrypoint for correlation, wraps individual checks.

Parameters:scan_bolus (tuple) – Position 0 contains a string defining scan type. If it’s type ‘gps’, the geo_state instance variable will be updated with Position 1’s contents. If the scan type is ‘kal_channel’, we perform feed and threshold comparison. any other scan type will be compared against the feed only. Returns:

Returns a list of alerts. If no alerts are generated, an

empty list is returned.

Return type:list

feed_alert_generator(arfcn)

Wrap the yield_arfcn_from_feed function, and generates alerts.

Parameters:arfcn (str) – This is the string representation of the ARFCN to be correlated. Returns:This returns a list of alert tuples. Return type:list

classmethod is_in_range(item_gps, state_gps)

Return True if items are within 40km.

manage_arfcn_lists(direction, arfcn, aspect)

Manage the instance variable lists of ARFCNs.

This is necessary to maintain an accurate state over time, and reduce unnecessary noise.

Parameters:

• direction (str) – Only will take action if this is “in” or “out”
• arfcn (str) – This is the ARFCN that will be moved in or our of the list
• aspect (str) – This is used to match the ARFCN with the list it should be moved in or out of. This should be either “threshold” or “not_in_range”.

classmethod yield_arfcn_from_feed(arfcn, states, feed_dir)

Iterate over the feed files, yielding licenses for target ARFCN.

Parameters:

• arfcn (str) – Target ARFCN.
• states (list) – List of US state postal codes, corresponding to feed files.
• feed_dir (str) – Base directory for feed files.

Yields:

dict – Feed row for ARFCN

CgiCorrelator

class sitchlib.CgiCorrelator(feed_dir, cgi_whitelist, mcc_list, device_id)

The CgiCorrelator compares CGI addressing against the OpenCellID DB.

The feed data is put in place by the FeedManager class, prior to instantiating the CgiCorrelator.

classmethod arfcn_int(arfcn)

Attempt to derive an integer representation of ARFCN.

Parameters:arfcn (str) – String representation of ARFCN Returns:Integer representation of ARFCN, zero if unable to convert. Return type:int

classmethod bts_from_channel(channel)

Create a simplified representation of BTS metadata.

Parameters:channel (dict) – Returns:Contains MCC, MNC, LAC, and cellid Return type:dict

classmethod build_chan_here(channel, state)

Build geo information for channel, to aid in geo correlation.

Parameters:

• channel (dict) – Channel metadata
• state (dict) – Geo-json representing the current location of the sensor

Returns:

Original channel structure, with the current sensor location

embedded.

Return type:

dict

classmethod cell_matches(cell, mcc, mnc, lac, cellid)

Compare cell metadata against mcc, mnc, lac, cellid.

classmethod cgi_whitelist_message(cgi_wl)

Format and return the CGI whitelist initialization message.

Parameters:cgi_wl (list) – CGI whitelist Returns:Formatted message Return type:str

classmethod channel_in_feed_db(channel)

Return True if channel geo metadata is complete.

classmethod channel_out_of_range(channel)

Check to see if sensor is out of range for CGI.

Parameters:channel (dict) – Channel metadata Returns:True if the sensor is in range of the detected CGI Return type:bool

check_channel_against_feed(channel)

Determine whether or not to fire an alert for CGI presence in feed.

Parameters:channel (dict) – Channel metadata Returns:

Empty if there is no alert, a two-item tuple if an alert

is generated.

Return type:tuple

check_channel_range(channel)

Check to see if the detected CGI is in range.

Parameters:channel (dict) – Channel metadata, enriched with feed info. Returns:

Empry if no alert is generated. A two-item tuple if an

alert condition is detected.

Return type:tuple

classmethod convert_float_targets(channel)

Convert string values for rxq and rxl to floating point.

classmethod convert_hex_targets(channel)

Convert lac and cellid from hex to decimal.

correlate(scan_bolus)

Entrypoint for the CGI correlation component.

Parameters:scan_bolus (tuple) – scan_bolus[0] contains the scan type. If the type is ‘gps’, it will set the correlator’s geo location. For other scan types, we expect them to look like gsm_modem_channel events, and they are compared against the feed database as well as state history, tracking things like the current active cell’s CGI. Returns:

Returns a list of tuples, representing alerts. If no alerts

fire, the list will be empty.

Return type:list

feed_comparison(channel)

Compare channel metadata against the feed DB.

This function wraps a few checks against the feed DB. It first checks

if the bts is in the feed DB. Next, it checks that the sensor is within range of the BTS in the feed DB. Finally, if it’s the primary channel, it checks to see if the primary BTS has changed.

Parameters:channel (dict) – Channel, enriched with geo information Returns:

If alarms are generated, they’ll be returned in a list of

tuples. Otherwise, an empty list comes back.

Return type:list

classmethod get_cgi_int(channel)

Attempt to create an integer representation of CGI.

get_feed_info(mcc, mnc, lac, cellid)

Check CGI against cache, then against the feed DB.

Parameters:

• mcc (str) – Mobile Country Code
• mnc (str) – Mobile Network Code
• lac (str) – Location Area Code
• cellid (str) – Cell ID

Returns:

Dictionary containing feed information for CGI

Return type:

dict

get_feed_info_from_db(mcc, mnc, lac, cellid)

Interrogate DB for CGI information.

Parameters:

• (str) – Mobile Country Code
• mnc (str) – Mobile Network Code
• lac (str) – Location Area Code
• cellid (str) – Cell ID

Returns:

Dictionary containing feed information for CGI. If no

information exists, the feed geo information will be zeroed out…

Return type:

dict

classmethod make_bts_friendly(bts_struct)

Create a human-friendly representation of CGI.

Parameters:bts_struct (dict) – Simple structure containing CGI components. Returns:

String reperesentation of CGI, with items being

colon-separated.

Return type:str

classmethod normalize_feed_info_for_cache(feed_item)

Normalize field keys for the feed cache.

classmethod primary_bts_changed(prior_bts, channel, cgi_whitelist)

Create alarms if primary BTS metadats changed.

Parameters:

• prior_bts (str) – Current primary BTS
• channel (dict) – Channel metadata
• cgi_whitelist – Whitelist of CGIs to NOT alert on

Returns:

True if the primary BTS has changed and the new BTS in not

on the whitelist. False otherwise.

Return type:

bool

process_cell_zero(channel)

Process channel zero.

Parameters:channel (dict) – Channel metadata. Returns:

Empry if there is no alert, a two-item tuple if an alert

condition is detected.

Return type:tuple

classmethod should_skip_feed(channel)

Examine channel info to determine if feed comparison should happen.

Parameters:channel (dict) – Channel information. Returns:True if channel information is complete, False if not. Return type:bool

ConfigHelper

class sitchlib.ConfigHelper(sitch_var_base_dir='/data/sitch/')

Manage configuration information for entire SITCH Sensor.

build_logrotate_config()

Generate logrotate config file contents.

classmethod get_device_id()

Get device ID from env var.

classmethod get_filebeat_template(filename='/etc/templates/filebeat.json')

Get the filebeat config from template file.

classmethod get_from_env(k)

Get configuration items from env vars. Hard exit if not set.

get_gps_device_port()

Get GPS device from detector, override with env var.

get_gsm_modem_port()

Get GSM modem port from detector, override with env var.

classmethod get_list_from_env(k, optional=False)

Get a list from environment variables.

If optional=True, the absence of this var will cause a hard exit.

get_secret_from_vault()

Retrieve secrets from Vault.

print_devices_as_detected()

Print detected GPS and GSM devices.

classmethod set_filebeat_logfile_paths(log_prefix, filebeat_config)

Sets all log file paths to align with configured log prefix.

write_filebeat_config()

Write out filebeat config to file.

Decomposer

class sitchlib.Decomposer

Decompose device messages into normalized log messages.

classmethod decompose(scan)

Direct messages to the correct decomposer.

DeviceDetector

class sitchlib.DeviceDetector

Interrogate all USB TTY ports.

gsm_radios

This is a list of GSM radios, represented in dict type objects.

Type:list

gps_devices

This is a list of GPS devices. Just strings like ‘/dev/ttyUSB0’.

Type:list

classmethod find_gps_radios(usbtty_ports)

Interrogate USB TTY ports, return a list of GPS devices.

classmethod find_gsm_radios(usbtty_ports)

Interrogate USB TTY ports, return GSM radios.

classmethod get_devices_by_subsys(type)

Get devices from udev, by type.

classmethod get_gsm_modem_info(port)

Get modem information.

Parameters:port (str) – Device/port to interrogate. Returns:

metadata describing modem manufacturer, model, revision,

and serial.

Return type:dict

classmethod interrogate_gsm_modem(port, command)

Issue command on port, return output.

Parameters:

• port (str) – Port/device to interrogate.
• commmand (str) – Command to be issued.

Returns:

Response from device, if any. If none, returns an empty

string.

Return type:

str

classmethod interrogator(match_list, port, test_command=None)

Interrogate serial port, and attempt to match output.

Parameters:

• match_list (list) – List of strings that positively identify a device of a specific type.
• port (str) – Port to be interrogated.
• test_command (str) – Command to trigger output to match against match_list.

Returns:

True if the device is a positive match, False if not.

Return type:

bool

classmethod interrogator_matcher(matchers, line)

Attempt to match output against known identifing strings.

Parameters:

• matchers (list) – List of strings which represent positive matches.
• line (str) – Output from USB TTY device.

Returns:

True if it’s a match, False if not.

Return type:

bool

classmethod is_a_gps(port)

Wrap interrogator for determining when a GPS is discovered.

classmethod is_a_gsm_modem(port)

Wrap interrogator for determining when a GSM modem is discovered.

FccFeed

class sitchlib.fcc_feed.FccFeed(states, feed_base)

Wrap the FCC Feed with an iterator.

build_feed_file_names(states, feed_base)

Construct full feed file path.

FeedManager

class sitchlib.FeedManager(config)

Manage downloading the feed DB, and merging it into the sqlite DB.

classmethod cgi_csv_dump_to_db(schema, feed_file, db_file, target_radios, last_upd=0)

Merge CSV into DB, taking into account the record update time.

Parameters:

• schema (list) – List of rows in DB.
• feed_file (str) – Path to feed CSV file.
• db_file (str) – Path to sqlite DB file.
• last_upd (int, optional) – Epoch time. Records updated before this date will not be inserted into the DB.

classmethod cgi_mass_insert(schema, rows, db_file)

Mass-insert records into the DB.

Parameters:

• schema (list) – List of DB fields.
• rows (list) – List of tuples, each tuple contains values corresponding to the keys in schema.
• db_file (str) – Path to sqlite file.

classmethod create_and_populate_cgi_db(schema, feed_files, db_file, target_radios)

Create DB, then merge all records from file.

Parameters:

• schema (list) – List of DB fields.
• feed_files (list) – List of feed files to be merged.
• db_file (str) – Full path of CGI DB file.

Returns:

Most recent timestamp from merge.

Return type:

str

classmethod create_cgi_db(cgi_db)

Create a DB for CGIs.

This DB has only one table, named cgi and the mcc+mnc+lac+cellid is

unique.

Parameters:cgi_db (str) – Path to CGI DB.

get_newest_record_time()

Get the newest record time from file in feed dir.

classmethod get_source_url(url_base, mcc)

Create source URL for MCC file.

Parameters:

• url_base (str) – Base URL for MCC file.
• mcc (str) – MCC for feed file.

classmethod merge_feed_files_into_db(schema, feed_files, db_file, target_radios, last_upd)

Wrapper for merging feed file data into CGI DB.

Parameters:

• schema (list) – List of fields in DB
• feed_file (str) – Path to feed file to be merged into CGI DB.
• db_file (str) – Path to CGI DB file.
• last_upd (str) – Epoch time stamp, will not attempt to merge any records with timestamps before this time.

Returns:

Most recent timestamp from merged feed file.

Return type:

str

classmethod place_feed_file(feed_dir, url_base, item_id)

Retrieve and places feed files for use by the Enricher modules.

Parameters:

• feed_dir (str) – Destination directory for feed files
• url_base (str) – Base URL for hosted feed files
• item_id (str) –

  For FCC, this is the two-letter (“CA” or “TN”, for example), which is used in the retrieval of the feed file

  as well as the construction of the local feed file name. For MCC this is the MCC, but in string form. Not integer.

classmethod reconcile_cgi_db(feed_files, db_file, target_radios, last_update)

Reconcile all feed files against the CGI DB.

Parameters:

• feed_files (list) – List of paths to feed files.
• db_file (str) – Full path to CGI DB file.
• last_update (str) – Epoch time of most recent record in DB

Returns:

Epoch timestamp of most recently updated DB record.

Return type:

str

set_newest_record_time(timestamp)

Set the newest record time.

Parameters:timestamp (str) – Epoch time to be written to file If not string, will be coerced to string.

classmethod should_update_record(anchor_time, update_time)

Compare timestamps to determine if a record should be updated.

classmethod tup_from_row(schema, row)

Convert a row into a tuple, for insertion into DB.

Parameters:

• schema (list) – Field list for DB.
• row (dict) – Row of data. Keys align with items in schema.

Returns:

Tuple representing values to be inserted into DB, ordered

by fields in schema.

Return type:

tuple

update_feed_db()

Wrapper for feed file reconciliation against CGI DB.

update_feed_files()

Wrapper for feed file retrieval routines.

GeoCorrelator

class sitchlib.GeoCorrelator(device_id)

Geographic correlator.

correlate(scan_bolus)

Correlate one geo event.

The first time we get a geo event, we set the state and print a message

to stdout to that effect. Every subsequent message is compared against the geo_anchor. Once the anchor is set, it does not change for the life of the instance. Correlation of subsequent events causes the distance beween the anchor and current event to be determined and if the threshold of 10km is exceeded, an alert is returned.

Parameters:scan_bolus (tuple) – Two-item tuple. Position 0 contains the scan type, which is not checked. We should only ever have geo events coming through this method. Position 1 is expected to contain geo json. Returns:

List of alerts. If no alerts are fired, the list returned is

zero-length.

Return type:list

classmethod geo_drift_check(geo_anchor, gps_scan, threshold, device_id)

Fire alarm if distance between points exceeds threshold.

Parameters:

• geo_anchor (dict) – Geographic anchor point, usually stored in an instance variable and passed in via the correlate() method.
• gps_scan (dict) – Same format as geo_anchor, expects the same format as geo_anchor.
• threshold (int) – Alerting threshold in km.

Returns:

list of alerts (usually just one) or an empty list of there

are no alerts.

Return type:

list

classmethod time_drift_check(gps_scan, threshold_mins, device_id)

Checks drift value, alarms if beyond threshold.

GeoIp

class sitchlib.GeoIp(delay=60)

Generate GeoIP events.

set_geo()

Use public IP to determine GeoIP.

set_ip()

Set public IP address.

GeoipDecomposer

class sitchlib.geoip_decomposer.GeoipDecomposer

GeoIP Decomposer.

classmethod decompose(scan_document)

Validate and decompose GeoIP Events.

Parameters:scan_document (dict) – GeoIP scan document. Returns:

one item in list: a two-item tuple. Position 0 is geo_ip.

Position 1 is the actual scan document. If the scan fails validation, you’ll only get an empty list back

Return type:list

classmethod scan_document_is_valid(scan_document)

Validate the scan document.

GpsDecomposer

class sitchlib.gps_decomposer.GpsDecomposer

GPS Decomposer.

classmethod decompose(scan_document)

Decompose a GPS event.

Parameters:scan_document (dict) – Geo json from GPS device. Returns:

One two-item tuple in list. Position 0 is gps, position 1

is the validated geo scan. If the scan doesn’t validate, an empty list is returned.

Return type:list

classmethod scan_document_is_valid(scan_document)

Validate the scan document.

GpsListener

class sitchlib.GpsListener(delay=60)

Wrap the GPS device with an iterator.

classmethod get_time_delta(iso_1, iso_2)

Get the drift, in minutes, between two ISO times.

GsmDecomposer

class sitchlib.gsm_decomposer.GsmDecomposer

Decomposes GSM scans.

classmethod arfcn_int(arfcn)

Attempt to derive an integer representation of ARFCN.

classmethod bts_from_channel(channel)

Return clean BTS from channel.

classmethod convert_float_targets(channel)

Convert rxq and rxl to float.

classmethod convert_hex_targets(channel)

Convert LAC anc CellID from hex to decimal.

classmethod decompose(scan_document)

Turn one scan document into a list of channel scan documents.

Parameters:scan_document (dict) – GSM modem scan. Returns:

List of tuples. First position in tuple identifies scan

type. Second position is the actual scan data.

Return type:list

classmethod enrich_channel_with_scan(channel, scan_document)

Enrich channel with scan document metadata.

classmethod get_cgi_int(channel)

Attempt to create an integer representation of CGI.

classmethod make_bts_friendly(bts_struct)

Expect a dict with keys for mcc, mnc, lac, cellid.

GsmModem

class sitchlib.GsmModem(ser_port)

GSM Modem handler class. Interfaces with device over serial.

Calling GsmModem.set_eng_mode() causes the module to go into

engineering mode, which will cause it to return cell network information. It has an iterator (generator) built in that cranks out dicts.

classmethod clean_operator_string(operator_string)

Clean up the operator string.

dump_config()

Dump modem’s configuration.

eng_mode(status)

Set or unset engineering mode on the modem.

Parameters:status (bool) – True to enable engineering mode, False to disable.

get_imsi()

Get the IMSI of the SIM installed in the modem.

get_reg_info()

Get registration information from the modem.

classmethod process_12(parts)

Process a 12-part CENG message.

Parameters:parts (list) – Parts parsed from original CENG message. Returns:Structured cell channel metadata. Return type:dict

classmethod process_7(parts)

Process a 12-part CENG message.

In a 7-item line, cellid is not provided. We set

it to 0 to prevent barfing elsewhere.

Parameters:parts (list) – Parts parsed from original CENG message. Returns:Structured cell channel metadata. Return type:dict

classmethod process_8(parts)

Process an 8-part CENG message.

Parameters:parts (list) – Parts parsed from original CENG message. Returns:Structured cell channel metadata. Return type:dict

classmethod process_line(line)

Process line output from GSM modem.

We expect to see only lines starting with +CENG:. Otherwise, it’s

an empty dictionary getting returned.

Parameters:line (str) – Raw line output from GSM modem. Returns:Structured data parsed from line. Return type:dict

set_band(band)

Set the band the GSM modem should communicate on.

If the band does not set correctly, an error will print to stdout and the original setting will persist.

Parameters:band (str) – Pick one: EGSM_MODE, PGSM_MODE, DCS_MODE, GSM850_MODE, PCS_MODE, EGSM_DCS_MODE, GSM850_PCS_MODE, EGSM_PCS_MODE, or ALL_BAND.

KalDecomposer

class sitchlib.kal_decomposer.KalDecomposer

Decompose Kalibrate scans.

classmethod decompose(scan_document)

Decompose Kalibrate scans into channels.

The first item in each returned tuple indicates the scan doc type.

This module produces: “scan” (Kalibrate scan doc) and “kal_channel” (Individual channel from Kalibrate scan)

Parameters:scan_document (dict) – Output from Kalibrate as interpreted by kalibrate Python module.

LocationTool

class sitchlib.LocationTool

Class with location-oriented functions.

classmethod get_distance_between_points(point_1, point_2)

Calculate distance between points.

Parameters:

• point_1 (tuple) – (lon, lat) for first point.
• point_2 (tuple) – (lon, lat) for second point.

Returns:

Kilometers between point_1 and point_2.

Return type:

int

classmethod get_geo_for_ip(ip_address)

Get geo coordinates for IP address.

Parameters:ip_address (str) – IP address.

classmethod validate_geo(latlon)

Validate that lon/lat are valid numbers for Planet Earth

Logger

class sitchlib.LogHandler(config)

Instantiate this class with the log file prefix.

classmethod get_log_file_name(ltype)

Get the name of the appropriate log file for the message type.

Parameters:ltype (str) – Log type Returns:Log file name Return type:str

record_log_message(bolus)

Determine log file for message and send to the writer.

write_log_message(log_file_type, message)

Write message to disk.

Parameters:

• log_file_type (str) – Type of log message
• message (str) – Message to be logged to disk

Utility

class sitchlib.Utility

General utility class.

classmethod calculate_distance(lon_1, lat_1, lon_2, lat_2)

Wrap the LocationTool.get_distance_between_points() fn.

classmethod construct_feed_file_name(feed_dir, prefix)

Construct full path for feed file.

classmethod create_file_if_nonexistent(path, lfile)

Create file and path, if it doesn’t already exist.

classmethod create_path_if_nonexistent(path)

Create filesystem directory path.

classmethod dt_delta_in_minutes(dt_1, dt_2)

Calculate the delta between two datetime objects, in minutes.

classmethod dt_from_iso(iso_time)

Exchange an ISO8601-formatted string for a datetime object.

classmethod epoch_to_iso8601(unix_time)

Transform epoch time to ISO8601 format.

classmethod get_now_string()

Get ISO8601 timestamp for now.

classmethod get_performance_metrics(queue_sizes={})

Get sensor hardware and os performance statistics.

classmethod get_platform_info()

Get information on platform and hardware.

classmethod get_platform_name()

Get platform name from lshw output.

classmethod get_public_ip()

Get public IP.

classmethod heartbeat(service_name)

Generate heartbeat message.

classmethod hex_to_dec(hx)

Change hex to decimal.

classmethod is_valid_json(in_str)

Test string for json validity.

classmethod pretty_string(structure)

Pretty-print lines.

classmethod start_component(runcmd)

Start a thing.

classmethod str_to_float(s)

Change string to float.

classmethod strip_list(raw_struct)

Strip contents from single-item list.

classmethod write_file(location, contents)

Write string to file.

Indices and tables

• Index
• Module Index
• Search Page