Skip to content

Interface metadata format

Jump to bottom Edit New page
Kristian Evensen edited this page Feb 24, 2016 · 1 revision

Metadata exporter is part of the Network Listener tool and it's responsible to export informations as JSON object. Actual modem state is exported when when ICCID/IMSI numbers are available. Example of JSON object of exported metadata:

  • For LTE networks:
{"timestamp":1456228034,"event_type":1,"iccid":"89480610500302602379",
"imsi":"260060080260237","imei":"866948011255141","imsi_mccmnc":26006,
"network_mccmnc":26006,"device_mode":5,"device_sub_mode":0,"isp_name":"Play",
"lte_rssi":-73,"lte_rsrp":-96,"lte_rsrq":-8,"lac":32,"cid":3262520,"lte_pci":13,
"enodeb_id":3262520,"ip_addr":"10.126.156.213","internal_ip_addr":"192.168.32.113",
"lte_band":3,"lte_freq":1800,"device_state":3,"event_param":6,"ifname":"usb0"}
  • For UMTS/CDMA networks:
{"timestamp":1456228850,"event_type":1,"iccid":"89480610500302602379",
"imsi":"260060080260237","imei":"861311010197670","imsi_mccmnc":26006,
"network_mccmnc":26006,"device_mode":4,"device_sub_mode":2,"isp_name":"Play"
,"rssi":-82,"ecio":-4,"lac":32,"cid":2258959,"ip_addr":"10.122.105.88",
"device_state":3,"event_param":6,"ifname":"usb0"}

Data is exported on event or timeout. Timeout is set to 30s. Implemented events are:

DEVICE STATE CHANGED (1) - sent when device state is changed (see possible states below)
MODE CHANGED (2) - sent when there is a connection state change (for example 3G connection changed to LTE)
SIGNAL STRENGTH CHANGED (3) - sent when signal strength changed
LTE BAND CHANGED (4) - sent when LTE band is changed (only valid for LTE capable modems)
ISP NAME CHANGED (5) - sent when ISP name has changed
META UPDATE (6) - this event is sent periodically (every 30s) and contains all available informations about modem at the moment
IP ADDRESS CHANGED (7) - sent when external IP has changed (for example due to end of DHCP lease)
LOCATION CHANGED (8) - sent when LAC (Location Area Code), CID (Cell ID), LTE PCI (LTE Physical Cell ID) or EnodeBId (E-UTRAN NodeB ID) has changed
NETWORK MCC/MNC CHANGED (9) - sent when values of MCC (Mobile Country Code) or MNC (Mobile Network Code) read from network has changed

For now network listener exports following data:

ICCID - Integrated Circuit Card Identifier (unique for SIM card)
IMEI - International Mobile Equipment Identity
IMSI - International Mobile Subscriber Identity
ifname - Interface name of device (if available)
IMSI MCC/MNC - Mobile Country Code / Mobile Network Code from IMSI number (read from SIM card)
NETWORK MCC/MNC - Mobile Country Code / Mobile Network Code from network (read from network)
DEVICE MODE - connection mode of the modem (2G, 3G, LTE, etc.)
DEVICE SUBMODE - connection submode for 3G connections (CDMA, WCDMA, UMTS, etc.)
ISP NAME - network provider name
RSSI - Received Signal Strength Indicator
ECIO - ratio of the received energy per chip and the interference level,(valid only for UMTS/CDMA networks)
RSCP - Received Signal Code Power (valid only for UMTS/CDMA networks)
RSRP - Reference Signal Received {ower (valid only for LTE networks)
RSRQ - Reference Signal Recieved Quality (valid only for LTE networks)
LAC - Location Area Code
CID - Cell Identifier
LTE PCI - LTE Physical Cell ID ** E-NODEB ID** - E-UTRAN NodeB ID LTE BAND - LTE band number (valid only for LTE networks)
LTE FREQUENCY - LTE frequency (valid only for LTE networks)
IP ADRESS - is the external IP address assigned by ISP
INTERNAL IP ADRRESS - some devices uses NAT, so this is internal IP address assigned to the device client
DEVICE STATE - state of the device (see below)


Device state can be folowing:

**UNKNOWN (0)** - device state is unknwon
**REGISTERED (1)** - device is registered to the network
**UNREGISTERED (2)** - device is unregistered from the network
**CONNECTED (3)** - device is connected to the network
**DISCONNECTED (4)** - device is disconnected from the netwrok

When network listener exports data using events then only relevant data are exported. See examples below:

  • Event DEVICE STATE CHANGED is sent when modem is registered/unregistered/connected/disconnected to/from the network:

if modem state is unknown them device_state is set to 0:

{"timestamp":1456228601,"event_type":1,"iccid":"89480610500302602379",
"imsi":"260060080260237","imei":"861311010197670","device_state":0,
"event_param":1,"ifname":"usb0"}

If modem is registered to the network then device_state is set to 1:

{"timestamp":1456228801,"event_type":1,"iccid":"89480610500302602379",
"imsi":"260060080260237","imei":"861311010197670","device_state":1,
"event_param":1,"ifname":"usb0"}

If modem is unregistered from the network then device_state is set to 2:

{"timestamp":1455881286,"event_type":1,"iccid":"89480610500302602379",
"imsi":"260060080260237","imei":"866948011255141","device_state":2,
"event_param":1,"ifname":"usb0"}

If modem is connected to the network then device_state is set to 3:

{"timestamp":1456228801,"event_type":1,"iccid":"89480610500302602379",
"imsi":"260060080260237","imei":"861311010197670","device_state":3,
"event_param":1,"ifname":"usb0"}

If modem is disconnected from the network then device_state is set to 4:

{"timestamp":1456228801,"event_type":1,"iccid":"89480610500302602379",
"imsi":"260060080260237","imei":"861311010197670","device_state":4,
"event_param":1,"ifname":"usb0"}

* Event **MODE CHANGED** is sent when change in device mode (2G, 3G, LTE) or device submode when mode is 3G (UMTS, WCDMA, HSPA, etc.): 
{"timestamp":1456228490,"event_type":1,"iccid":"89480610500302602379",
"imsi":"260060080260237","imei":"861311010197670","device_mode":5,
"device_sub_mode":0,"event_param":2,"ifname":"usb0"}

For example if 3G network submode from UMTS to DC-HSPA+ exported data is following:

{"timestamp":1453799365,"event_type":1,"iccid":"8948022214021296473",
"imsi":"260021822129647","imei":"866948013972495","device_mode":4,
"device_sub_mode":7,"event_param":2,"ifname":"usb0"}

Device Mode is one of the following values: UNKNOWN (0), DISCONNECTED (1), NO SERVICE (2), 2G (3), 3G (4), LTE (5)

Device submode is one of the following values: UNKNOWN (0), UMTS (1), WCDMA (2), EVDO (3), HSPA (4), HSPA+ (5), DC HSPA (6), DC HSPA+ (7), HSDPA (8), HSUPA (9), HSDPA HSUPA (10), HSDPA+ (11), HSDPA+HSUPA (12), DC HSDPA+ (13), DC HSDPA+HSUPA (14)


* Event **SIGNAL STRENGTH CHANGE** is sent when there is a change in RSSI value:

For UMTS/CDMA there is additional infomation about signal beside RSSI when available - ECIO and RSCP

{"timestamp":1455889019,"event_type":1,"iccid":"89480610500302602379",
"imsi":"260060080260237","imei":"866948011255141","rssi":-78,"ecio":-10,
"rscp":-88,"event_param":3,"ifname":"usb0"}

For LTE networks there is additional parameters available beside RSSI when available - RSRQ and RSRP:

{"timestamp":1455881893,"event_type":1,"iccid":"89480610500302602379",
"imsi":"260060080260237","imei":"866948011255141","lte_rssi":-73,
"lte_rsrp":-96,"lte_rsrq":-8,"event_param":3,"ifname":"usb0"}

* Event **LTE BAND CHANGED** is sent when there is a change in LTE band and/or LTE frequency: 
{"timestamp":1453382715,"event_type":1,"iccid":"89480610500302602379",
"imsi":"260060080260237","imei":"866948013972495","lte_band":3,
"lte_freq":1800,"event_param":4,"ifname":"usb0"}

This signal is send only for LTE networks. When we switch from LTE to 3G then MODE CHANGED signal is sent.


* Event **ISP NAME CHANGED** is sent when there is a change in service provider name: 
{"timestamp":1453821612,"event_type":1,"iccid":"89480610500302602319",
"imsi":"260021822129647","imei":"866948013172495","isp_name":"T-Mobile",
"event_param":5,"ifname":"usb0"}

* Event **META UPDATE** is sent every 30s and contains all available data:

For LTE networks it looks as following:

{"timestamp":1456228700,"event_type":1,"iccid":"89480610500302602379",
"imsi":"260060080260237","imei":"861311010197670","imsi_mccmnc":26006,
"network_mccmnc":26006,"device_mode":5,"device_sub_mode":0,"isp_name":"Play",
"lte_rssi":-71,"lte_rsrp":-81,"lte_rsrq":-11,"lac":57760,"cid":3262520,
"ip_addr":"10.125.26.226","lte_band":3,"lte_freq":1800,"device_state":3,
"event_param":6,"ifname":"usb0"}

For UMTS/CDMA networks it looks as following:

{"timestamp":1456229450,"event_type":1,"iccid":"89480610500302602379",
"imsi":"260060080260237","imei":"861311010197670","imsi_mccmnc":26006,
"network_mccmnc":26006,"device_mode":4,"device_sub_mode":10,"isp_name":"Play",
"rssi":-83,"ecio":-4,"lac":32,"cid":2258959,"ip_addr":"10.122.105.88",
"device_state":3,"event_param":6,"ifname":"usb0"}

* Event **IP ADDRESS CHANGED** is sent when external IP address has changed:

When IP address is assigned then event looks as following:

{"timestamp":1456228490,"event_type":1,"iccid":"89480610500302602379",
"imsi":"260060080260237","imei":"861311010197670","ip_addr":"10.125.26.226",
"event_param":7,"ifname":"usb0"}

When IP address is unassigned then event looks as following:

{"timestamp":1456228801,"event_type":1,"iccid":"89480610500302602379",
"imsi":"260060080260237","imei":"861311010197670","event_param":7,"ifname":"usb0"}

* Event **LOCATION CHANGED** is sent when LAC, CID, LTE PCI or E-Utran Node B value has changed 
{"timestamp":1455881213,"event_type":1,"iccid":"89480610500302602379",
"imsi":"260060080260237","imei":"866948011255141","lac":32,"cid":3262520,
"lte_pci":13,"enodeb_id":3262520,"event_param":8,"ifname":"usb0"}

* Event **NETWORK MCC/MNC CHANGED** is sent when MCC or MNC values read from network has changed 
{"timestamp":1456229848,"event_type":1,"iccid":"89480610500302602379",
"imsi":"260060080260237","imei":"861311010197670","network_mccmnc":26006,
"event_param":9,"ifname":"usb0"}



Source for ISP NAME

Network Listener reads two values of MCC/MNC pair. First one is read from IMSI number as soon as we have SIM card ready. Based on IMSI number Network Listener uses database to match ISP name based on IMSI number (database with ISP names are generated based on http://mcc-mnc.com/ web site). In JSON output this value is sent as **imsi_mccmnc**. As soon as modem is registered to the network we read MCC/MNC pair from the network. In JSON output this value is sent as **network_mccmnc**. If it's possible Network Listener reads ISP name from the network. In this case name of the ISP will be changed (in most cases). Especially in case of MVNO (Mobile Virtual Network Operator) which in most cases share MCC/MNC with the parent network this name will be changed.

For example in Poland there is T-Mobile PL operator which has MCC-MNC: 26002. And there is also Heyah virtual operator which uses the same values of MCC-MNC. So as soon as Network Listener reads IMSI number it changes ISP name to T-Mobile PL. When SIM card is registered to network and modem is able to get ISP name from the network isp_name will be changed to Heyah.



Command line option to send more data with each event

Network Listener is designed to send events with minimum amount of data. Events are designed to send only data with changed values. The only update with all available data is sent every 30s with META UPDATE event. If there is a need to send all the events wit all available data Network Listener must be run with **-e** command line option.

Add a custom footer
Add a custom sidebar
Clone this wiki locally