Cell survey app

Our cell survey app is designed for projects where you wish to do a survey of cellular performance in a particular area, such as in a disaster zones, to identify spots with lack of coverage or for drive-testing to test out how your cellular networks are performing in real-world conditions. It includes a vast array of environmental data and will continuously run download, upload and/or latency tests in order for you to perform a survey of the area whilst on the move.

Requirements

Android 8.0+ are the only supported versions. We also recommend a high-performance phone, in our testing we utilise a Samsung Galaxy S8.

When running tests there are also a few environmental requirements:

  • Make sure battery is running at more than 50% (keeping it plugged in is recommended)
  • Ensure power saving mode is not enabled (high-performance mode is recommended when available)
  • Ensure location is set to maximum accuracy
  • The app must run in the foreground and the phone must not be put to sleep

We also recommend that phones are not kept on top of each other as they can become warm after long period of intensive testing and the phones may restart.

Tests and test configuration

The measurements included in the SamKnows Android SDK are Download/Upload throughput, Latency, Jitter, and Packet Loss.

You can specify which tests you wish to run and it will execute them in cycles. Each cycle will be in the order: Latency, Download, Upload omitting any not enabled test.

There are two configurable delays to account for factors such as buffer bloat:

  • The inter-test delay, which is the time delay between individual tests in a cycle. The default is 10 seconds.
  • The inter-cycle delay which is the time delay between different test cycles (a cycle consists of one run of all the enabled tests). The default is 10 seconds.

The minimum delays are 5 second and maximum delays are 999 seconds.

Download speed

These tests measure the download HTTP throughput in bits per second. The test will run for a fixed duration (in addition to a TCP warmup period). This time is configurable at runtime.

The duration default is 5 seconds, maximum is 30 seconds and minimum is 5 seconds.

You can view the test methodology here.

Upload speed

These tests measure the upload HTTP throughput in bits per second. The test will run for a fixed duration (in addition to a TCP warmup period). This time is configurable at runtime.

The duration default is 5 seconds, maximum is 30 seconds and minimum is 5 seconds.

You can view the test methodology here.

Latency, jitter and packet loss

This is a single test that provides three separate metrics upon completion: latency, jitter and packet loss. Only latency is shown in-app but all three metrics are submitted and visible in SamKnows One. You can configure the packet count, packet interval and test duration at runtime.

The duration default is 5 seconds, maximum is 30 seconds and minimum is 5 seconds. The packet count default is 200, maximum is 500, and minimum is 100.

You can view the test methodology here

Test server

Test servers for the project will be defined in a target group and the closest ten (or less) to a mobile device by geolocation will be returned to the device. The device will then list them along with their associated latency results from an ICMP ping. The user can then select the specific test server they wish to test against and that test server will be used for the duration of the test.

Results submission

All results are submitted to SamKnows One. Results are submitted at the end of every test cycle, if it was unable to submit results (for example due to poor network connectivity) then it will cache the result and submit them next time the app is opened. You can see if a result has been submitted or cached as it will show with a green or red icon on the right hand side of the test results screen.

If you're experiencing issues with results being submitted (they are showing up as red) due to network issues, simply open the app later on whilst connected to Wi-Fi and all cached results will be submitted.

The results data dictionaries (excluding environmental data) are as follows:

Download speed test

Field Description
agent_id Unique identifier for an individual unit
test_id Unique identifier to the test cycle
dtime Local device time test finished
dtime_utc Test finished device time converted to UTC
target Target hostname or IP address
address The IP address of the server (resolved by the client's DNS)
duration Time the test ran for in microseconds
bytes_total Total bytes downloaded across all connections
bytes_sec Running total of throughput, which is sum of speeds measured for each stream (in bytes/sec), from the start of the test to the current interval
warmup_time Time consumed for all the TCP streams to arrive at optimal window size (Units: microseconds)
warmup_bytes Bytes transferred for all the TCP streams during the warm-up phase.
threads The number of concurrent TCP connections used in the test
successes Number of successes (always 1 or 0 for this test)
failures Number of failures (always 1 or 0 for this test)

Upload speed test

Field Description
agent_id Unique identifier for an individual unit
test_id Unique identifier to the test cycle
dtime Local device time test finished
dtime_utc Test finished device time converted to UTC
target Target hostname or IP address
address The IP address of the server (resolved by the client's DNS)
duration Time the test ran for in microseconds
bytes_total Total bytes uploaded across all connections
bytes_sec Running total of throughput, which is sum of speeds measured for each stream (in bytes/sec), from the start of the test to the current interval
warmup_time Time consumed for all the TCP streams to arrive at optimal window size (Units: microseconds)
warmup_bytes Bytes transferred for all the TCP streams during the warm-up phase.
threads The number of concurrent TCP connections used in the test
successes Number of successes (always 1 or 0 for this test)
failures Number of failures (always 1 or 0 for this test)

Latency/jitter/packet loss UDP test

Field Description
agent_id Unique identifier for an individual unit
test_id Unique identifier to the test cycle
dtime Local device time test finished
dtime_utc Test finished device time converted to UTC
target Target hostname or IP address
status_code A status code indicating any error states (0 for no failure)
duration Total duration of test (Units: microseconds)
packet_size Size of each UDP Datagram (Units: Bytes)
stream_rate Rate at which the UDP stream is generated (Units: bits/sec)
packets_sent Number of packets sent in Upstream (measured by client)
packets_received Number of packets received in Upstream (measured by server)
jitter Downstream Jitter measured (Units microseconds)
rtt Average round trip time of all packets
mos Mean Opinion Score
successes Number of successes (always 1 or 0 for this test)
failures Number of failures (always 1 or 0 for this test)

Environmental data

Environmental data is collected at the beginning and end of a test. Therefore all fields are prefixed with beginning or end. When there is no prefix, it is data from the end of the test.

Name Field name Type Example Description LTE GSM CDMA WCDMA
Device: Carrier Name device_environment.carrier_name String EE The name of the carrier on the handset Y Y Y Y
Device: ISO Country Code device_environment.iso_country_code String gb ISO2 country code Y Y Y Y
Device: Operating System Version device_environment.operating_system_version String Android 8.0.0 The version of iOS or Android operating system on the device and Operating System (Android or iOS) Y Y Y Y
Device: Manufacturer device_environment.manufacturer String Samsung The device manufacturer Y Y Y Y
Device: Model device_environment.model String SM-G965F The device model Y Y Y Y
Location: Latitude location.lat Float -0.09613687644 Latitude as determined by GPS Y Y Y Y
Location: Longitude location.lon Float 51.50719166 Longitude as determined by GPS Y Y Y Y
Memory: Device Free memory.device_free Integer 95 The amount of free memory on the device in megabytes Y Y Y Y
Memory: App Used memory.app_used Integer 1796 The amount of memory used on the app in megabytes Y Y Y Y
Memory: Device Used memory.device_used Integer 95 The amount of memory used on the device in megabytes Y Y Y Y
Cross-traffic: RX Average Bytes per Second cross_traffic.rx_avg_bps Integer 5882 The average received device traffic in bytes per second during the course of the test Y Y Y Y
Cross-traffic: RX Peak Bytes per Second cross_traffic.rx_peak_bps Integer 22381 The peak received device traffic in bytes per second during the course of the test Y Y Y Y
Cross-traffic: TX Average Bytes per Second cross_traffic.tx_avg_bps Integer 160 The average transmitted device traffic in bytes per second during the course of the test Y Y Y Y
Cross-traffic: TX Peak Bytes per Second cross_traffic.tx_peak_bps Integer 660 The peak transmitted device traffic in bytes per second during the course of the test Y Y Y Y
Network: State network.state Enum (Associated, Associating, Authenticating, Completed, Disconnected, Dormant, Four Way Handshake, Group handshake, Inactive, Interface Disabled, Invalid, Scanning, Uninitalized) Disconnected Current connection state of the device at the end of the test Y Y Y Y
Network: Substate network.subtype_name Enum (1xRTT, CDMA, EDGE, GPRS, GSM, IDEN, EHRPD, EVDO-0, EVDO-A, EVDO-B, HSDPA, HSPA, HSPAP, HSUPA, IWLAN, TD-SCDMA, UMTS, LTE, UNKNOWN) LTE The specific technology in use Y Y Y Y
Network: Is roaming network.is_roaming Boolean FALSE Is the device currently roaming (internationally)? Y Y Y Y
Network: Is connected network.is_connected Boolean TRUE Is the device connected to a network at the time of results being sent? Y Y Y Y
Network: Is failover network.is_failover Boolean FALSE Indicates whether the current connection resulted from the device failing over from a disconnect from a different network Y Y Y Y
Telephony: Cellular Technology telephony.cellular_technology Enum (simless/2g/3g/4g) 4g The cellular technology in use when on mobile network Y Y Y Y
Telephony: Connection Type telephony.connection_type Enum (cell/wi-fi) cell The current connection type (Wi-Fi or cellular network) Y Y Y Y
Telephony: Mobile Network Code telephony.cell_signal.mobile_network_code Integer 234 The ITU-T E.212 Mobile Network Code (MNC) Y Y Y Y
Telephony: Mobile Country Code telephony.cell_signal.mobile_country_code Integer 12 The ITU-T E.212 Mobile Country Code (MCC) Y Y Y Y
Telephony: RSSI telephony.cell_signal.signal_strength Integer -89 The (RSSI) signal strength to the nearest cell tower Y Y Y Y
Telephony: RSSRP telephony.cell_signal.received_signal_power Integer -104 Signal Received Power Y Y Y Y
Telephony: RSSRQ telephony.cell_signal.received_signal_quality Integer -10 Signal Received Quality Y N N N
Telephony: RSSNR telephony.cell_signal.received_signal_noise_ratio Integer 3 Signal-Noise Ratio Y N N N
Telephony: TAC telephony.cell_signal.tracking_area_code Integer 1034 16-bit Tracking Area Code Y N N N
Telephony: PCI telephony.cell_signal.physical_cell_identity Integer 147 Physical Cell Id Y N N N
Telephony: CI telephony.cell_signal.cell_identity Integer 318494 28-bit Cell Identity Y N N N
Telephony: Bandwidth telephony.cell_signal.bandwidth Integer -2 Cell bandwidth in kHz Y N N N
Telephony: CQI telephony.cell_signal.channel_quality_indicator Integer 6 Channel Quality Indicator Y N N N
Telephony: ASU telephony.cell_signal.asu Integer 26 Arbitrary Strength Unit provided by Android APIs Y Y Y Y
Telephony: ARFCN telephony.cell_signal.absolute_rf_channel_number Integer 16-bit GSM Absolute RF Channel Number N Y N N
Telephony: Base Station ID telephony.cell_signal.base_station_identity_code Integer 7 6-bit Base Station Identity Code N Y Y N
Telephony: LAC telephony.cell_signal.location_area_code Integer 112 16-bit Location Area Code N Y N N
Telephony: CID telephony.cell_signal.cell_identity_id Integer 32233 16-bit GSM Cell Identity N Y N Y
Telephony: PSC telephony.cell_signal.primary_scrambling_code Integer 382 9-bit UMTS Primary Scrambling Code N N N Y
Telephony: Network ID telephony.cell_signal.network_id Integer 655 Cell Tower Network ID N N Y N
Telephony: System ID telephony.cell_signal.system_id Integer 40760 Cell tower System ID N N Y N
Telephony: Cell Tower Latitude telephony.cell_signal.longitude Integer -0.09613687644 Base station latitude N N Y N
Telephony: Cell Tower Longitude telephony.cell_signal.longitude Integer 51.50719166 Base station longitude N N Y N

Mapping and test results screen

During a test run environmental data and points are plotted on a map.

It also includes a grid which shows test cycle download, upload and latency results.

Distribution

The cell survey app will be pushed to respective users via Fabric, the deployment platform that allows app version to be pushed to custom distribution groups.

Email addresses of the users requiring the app should be provided to SamKnows ahead of release. Invites will be sent requesting the user install Fabric and once complete the app will be pushed to the device.