Router SDK

The Router SDK allows the full SamKnows measurement functionality to be integrated into a home broadband router. This is used by some of the world's largest ISPs to gain visibility into the end-to-end performance of their entire network - without the need to deploy any new hardware or carry out expensive visits to customer premises. Increasingly, the Router SDK is also being used for ensuring compliance with new regulations, such as Ofcom's Voluntary Code of Practice.

It is delivered as a software package, which an ISP can distribute to its entire estate of home routers via a firmware update.

The Router SDK includes all of the SamKnows QoS and QoE tests, as well as cross-traffic detection capabilities. All measurement results are reported to SamKnows One, which is also used to manage the measurement agents configuration. It can also integrate with existing TR-069 or SNMP platforms, allowing ISPs to manage the agent with their existing toolsets.

Integration options

SamKnows supports two different integration approaches. Broadly speaking, the first involves SamKnows doing the majority of the work, and the second involves the ISP or manufacturer doing the majority of the work. The two different approaches are offered in recognition of the fact that some ISPs outsource all of their CPE development, whilst others prefer to do most of it in-house.

Option 1: SamKnows performs the integration

Option 1 involves SamKnows carrying out the vast majority of the integration work. This option should be chosen if the ISP or manufacturer does not have the experience to integrate a third party's SDK into their firmware, or if significant custom development is required. Significant development can be required for cross-traffic detection in split-architecture devices, such as Intel PUMA6 or PUMA7 based devices.

The following materials are required in order for SamKnows to carry out an integration into a CPE:

  • A minimum of two CPE, running a firmware representative of the one being integrated into
  • Serial/USB console or SSH access to the above CPE, with root access to the Linux shell
  • A toolchain that matches the firmware on the CPE

Before carrying out the complete integration, SamKnows will perform a feasibility study using the materials provided above. The feasibility study assesses the complexity of the integration, the development effort that is required, and also reports on the performance capabilities of the CPE with our measurements.

In this instance, an SDK tailored for the CPE in question will act as the final deliverable, including documentation detailing how to install it into the final firmware image.

Option 2: Manufacturer/ISP performs the integration

Option 2 involves the manufacturer or ISP performing the integration work. This option may be chosen if the integration is a straightforward one and the manufacturer/ISP is proficient in compiling and debugging C/C++ code. In this instance, our generic SDK is delivered to the manufacturer/ISP, alongside instructions that detail how it can be configured for different CPE.

Obtaining the SDK

The SDK is available to licenced users only and is delivered via a secure SamKnows FTP server. If you are already licenced to use the SDK, contact your SamKnows account manager to obtain the credentials to download it.

If you do not yet have a licence to use the SDK, please contact your SamKnows account manager or get in touch with us at info@samknows.com.

Hardware and software requirements

Hardware and software requirements for integrating the SamKnows measurements are minimal. Any router running a Linux-based operating system with a kernel version great than 2.6.32 can support the measurements.

Flash requirements vary according to the tests included in the SDK release and the presence of existing libraries in the router’s firmware. An SDK including only the core set of measurements (speed, latency and packet loss) represent can use as little as 200KB flash space. However, this can grow to 2MB if more complex measurements that require external libraries are required (video decoding libraries are particularly space intensive).

4MB of free RAM is sufficient to run the measurements. RAM will only be utilised when the measurements actually take place; at all other times only the test scheduler is running which will consume vastly less RAM than this.

The maximum attainable speed and CPU utilisation will vary according to the hardware. CPU is only utilised when measurements are running, which only last for approximately 10 seconds per measurement and also only operate when the connection is idle. A modern Intel Atom CPU at 1.2Ghz (as found in the PUMA 6 and PUMA 7 architectures) can measure 1Gbps throughput over TCP with approximately 20% CPU utilisation. Modern MIPS and ARM based SOCs can also saturate 1Gbps with CPU capacity to spare.

A first look at the SDK

The SDK contains the following components:

  1. A software licence agreement that outlines the terms under which the SDK has been provided
  2. Source code for the individual measurement clients (e.g. the speed test, latency test, Netflix test)
  3. Third party libraries we depend upon (e.g. libcurl, openssl, libevent, cron).
  4. Source code for the cross-traffic detection service
  5. Source code for the management client that allows configurations and test schedules to be remotely updated ("LMAP client")
  6. Customisations for the specific platform in use (e.g. specifying the path to the toolchain, linker flags, the interface to monitor for cross-traffic)
  7. The SamKnows build system, which ties all of the above together and builds the final binaries and overlay for the target firmware

The SDK is delivered as a single tarball (e.g. samknows-sdk-generic-1.0.0.tar.gz), which look similar to the following once extracted:

[sksam@toolchain1 samknows-sdk-generic-1.0.0]$ ll
      total 88
      drwxrwxr-x 4 sksam sksam 4096 May 20 11:35 build_system
      drwxrwxr-x 3 sksam sksam 4096 May 20 11:35 cdn_client
      drwxrwxr-x 2 sksam sksam 4096 May 20 11:35 dns_client
      drwxrwxr-x 5 sksam sksam 4096 May 20 11:35 ffmpeg
      drwxrwxr-x 3 sksam sksam 4096 May 20 11:35 flock
      drwxrwxr-x 2 sksam sksam 4096 May 20 11:35 http_test
      drwxrwxr-x 4 sksam sksam 4096 May 20 11:35 hulu
      drwxrwxr-x 5 sksam sksam 4096 May 20 11:35 iplayer
      drwxrwxr-x 4 sksam sksam 4096 May 20 11:35 jitter_client
      drwxrwxr-x 5 sksam sksam 4096 May 20 11:35 libcurl
      drwxrwxr-x 4 sksam sksam 4096 May 20 11:35 libsk
      drwxrwxr-x 3 sksam sksam 4096 May 20 11:35 libskcpp
      drwxrwxr-x 3 sksam sksam 4096 May 20 11:35 libskcpp2
      -rw-r--r-- 1 sksam sksam 3653 Apr 26 16:32 LICENCE.pdf
      drwxrwxr-x 3 sksam sksam 4096 May 20 11:35 lmap_packager
      -rw-r--r-- 1 sksam sksam 1364 Apr 26 16:24 Makefile
      drwxrwxr-x 4 sksam sksam 4096 May 20 11:35 netflix
      drwxrwxr-x 4 sksam sksam 4096 May 20 11:35 online_storage_client
      -rw-rw-r-- 1 sksam sksam 7845 May 20 11:35 README.md
      drwxrwxr-x 2 sksam sksam 4096 May 20 11:35 skpmontests
      drwxrwxr-x 3 sksam sksam 4096 May 20 11:35 timeout
      drwxrwxr-x 5 sksam sksam 4096 May 20 11:35 udplatencyclient
      drwxrwxr-x 5 sksam sksam 4096 May 20 11:35 webget
      drwxrwxr-x 6 sksam sksam 4096 May 20 11:35 youtube-test

Supported measurement clients

The SDK includes the following measurement clients:

Note: Your release of the SDK may include fewer measurement clients if you have opted not to licence them, or if you requested to exclude them in order to reduce the final build size.

Measurement client SDK directory
TCP speed test http_test
UDP latency/loss/disconnections (Continuous) udplatencyclient
DNS test dns_client
Web browsing test webget
UDP jitter/latency/loss (Instantaneous) jitter_client
Lightweight capacity test lct_client
Netflix test netflix
YouTube test youtube-test
Hulu test hulu
BBC iPlayer test iplayer
Online storage (Dropbox, Google drive) online_storage_client
ICMP ping skpmontests
CDN test cdn_client

Configuring the SDK

The Router SDK uses code (written in C and C++) which must be compiled for your CPE's platform natively. This necessitates the use of a toolchain that will allow us to cross-compile our source code for your platform. The generic Router SDK includes example configuration suitable for the Raspberry Pi 3 platform, but this can easily be replaced for your target platform.

Additional customisation beyond the toolchain is also required for managing cross-traffic detection and how the device will register with the SamKnows platform. This section details all of these changes.

Obtaining a toolchain for your platform

Your CPE manufacturer will be able to provide you with the toolchain for your device. These are often provided under licence from the chipset vendors (e.g. Broadcom, Intel and Qualcomm), so you may need to sign an agreement in order to obtain it.

Configuring your toolchain

The first step in building the SDK is to configure it to use your toolchain. To do this, create a file named ./build_system/units/Makefile.<your_platform>.

Your SamKnows account manager should provide you with the platform name to use. If you do not know this please contact your account manager. Platform names are unique identifiers for the hardware that is used in SamKnows One. They are formed of letters and numbers only. For example, rpi3 for Raspberry Pi 3. .

This should be populated with the following:

[sksam@toolchain1 samknows-sdk-generic-1.0.0]$ cat ./build_system/units/Makefile.rpi3
      TOOLCHAIN_DIR := /opt/samknows/raspberrypi/

      PATH := $(TOOLCHAIN_DIR)/bin:$(STAGING_DIR_HOST)/bin:$(PATH)
      SYSROOT := $(TOOLCHAIN_DIR)/armv7-rpi3-linux-gnueabihf/sysroot
      CROSS := armv7-rpi3-linux-gnueabihf-

      UNIT_CPPFLAGS := -idirafter $(SYSROOT)/usr/include
      UNIT_LDFLAGS := -L$(SYSROOT)/usr/lib  -L$(SYSROOT)/lib
      #CPU_CFLAGS := -mcpu=cortex-a53

      NO_RPATH := 1

The most important variables here are TOOLCHAIN_DIR, SYSROOT and CROSS. At a minimum, these need to be customised for your toolchain.

Configuring the device settings

Create a file ./lmap_packager/src/base/<your_platform>/device.mk that looks like the following:

[sksam@toolchain1 samknows-sdk-generic-1.0.0]$ cat ./lmap_packager/src/base/rpi3/device.mk
      NEEDS_SAMKNOWS_CERT := y
      MODEL_NAME := rpi3

MODEL_NAME should be set to your platform name used earlier.

Configuring the client ID

The client ID determines which SamKnows client the CPE is associated with when it comes online and registers with SamKnows' backend. It is important to set this correctly, otherwise your CPE will not be able to download a test schedule and will not execute measurements.

You need to obtain your client ID from your SamKnows account manager. This will look something like "ACMECorp".

Create a file ./lmap_packager/src/base/<your_platform>/scripts/base/listclient.sh with the following contents:

[sksam@toolchain1 samknows-sdk-generic-1.0.0]$ cat ./lmap_packager/src/base/rpi3/scripts/base/listclient.sh
      #!/bin/sh

      CLIENT="ACMECorp"
      UNIT_MODEL=$(cat '@SK_PREFIX@'/etc/unit_model)

      printf "autoregister=true&base=%s&client=%s" "$UNIT_MODEL" "$CLIENT"
      exit 0

Configuring a per-device identifier

Each CPE with the SamKnows SDK installed needs to be uniquely identifiable. This allows the results to be segregated by device and for different test schedules to be applied to different devices.

The most common way of uniquely identifying the CPE is to use the MAC address of CPE (or, more specifically, one of the MAC addresses, as many CPE will have multiple MACs). Most commonly, customers choose to use the MAC address that matches the one that is printed on the label on the underside of the CPE. This is usually the WAN interface's MAC address, but it depends on the device. You need to work out which interface this maps to in your firmware. This will typically be eth0 or similar.

To configure the MAC address that is used to uniquely identify this device, create a file named ./lmap_packager/src/base/<your_platform>/scripts/base/listmacaddresses.sh with the following:

[sksam@toolchain1 samknows-sdk-generic-1.0.0]$ cat ./lmap_packager/src/base/rpi3/scripts/base/listmacaddresses.sh
      #!/bin/sh

      MAC=ip addr show dev eth0 | grep ether | awk '{print $2}' | tr -d ':' | tr '[:lower:]' '[:upper:]'
      if [ -z "$MAC" ]; then
          exit 1
      fi

      printf 'mac=%s' "$MAC"
      exit 0

You should replace these commands with whatever is appropriate for your platform in order to obtain the MAC address. The above is suitable to obtain the MAC address for the eth0 interface for modern Linux based systems.

Customising cross-traffic detection

It is important that measurements do not execute whilst other users in the home are using the same broadband connection; to do otherwise would mean the measurements could be impaired and users' Internet experience could be harmed. This background traffic is known as "cross-traffic".

The Router SDK includes a cross-traffic detection agent which monitors one or more network interfaces for cross-traffic, and prevents measurements from running if cross-traffic is present.

In a typical CPE, only the WAN interface (e.g. the DOCSIS modem interface or the DSL modem interface) would need to be monitored, as all internet traffic will pass over this interface. It should not be necessary to also monitor the wireless interfaces or LAN-side Ethernet interfaces.

To configure the cross-traffic detection service, create a file named ./lmap_packager/src/base/<your_platform>/etc/bgtrafmon.cfg with the following:

PCAP_ETH_INTERFACE0=eth0
      #PCAP_WIFI_INTERFACE0=wlan1
      #PCAP_WIFI_INTERFACE1=wlan0

In the example above, eth0 is the WAN interface that is being monitored. Two wireless interfaces are also specified, but commented out.

CPU usage detection

CPE will typically performing other tasks than just performing the SamKnows measurements. Some services are particularly CPU intensive (e.g. file sharing from a NAS, or some Wi-Fi services). In these instances, it is desirable to not run measurements whilst the CPU is being heavily utilised - to do otherwise would harm the accuracy of the measurements.

The SDK includes functionality that checks CPU utilisation before carrying out measurements. This uses CPU counters found in /proc/stat to calculate the utilisation (as a percentage, based upon the past 1 second). If the CPU utilisation thresholds are exceeded then measurements are deferred 30 seconds and then reattempted.

The CPU utilisation threshold is configured remotely as a part of the test schedule (alongside cross-traffic thresholds). It is set to 15% by default and can be adjusted at any time.

Customising the installation path of the SDK (optional)

By default, the SamKnows SDK will expect to be installed to /opt/samknows in your devices firmware, and will write temporary files to /tmp/samknows (which typically maps to tmpfs).

To modify these paths, open the file Makefile and configure these parameters:

[sksam@toolchain1 samknows-sdk-generic-1.0.0]$ vi ./Makefile
      ...
      PREFIX := /opt/samknows
      SK_WORKINGDIR := /tmp/samknows
      ...

Customising the build parameters on a per measurement client basis

Some of the SamKnows measurement clients may require specific compilation flags your platform. For example, pthreadmay not be supported on your device, and one of our dependencies may assume that it is present. To configure per measurement client flags, create files named ./youtube-test/units/rpi3.mk with contents like the following:

youtube_LDFLAGS += -Wl,-rpath-link,/opt/samknows/raspberrypi/armv7-rpi3-linux-gnueabihf/lib
      CONFIGURE_ARGS += --with-ssl=/opt/samknows/raspberrypi/armv7-rpi3-linux-gnueabihf
      UNIT_CPPFLAGS += -pthread
      UNIT_LDFLAGS += -pthread

Building and installing the SDK

To compile the SDK for your platform, run:

make UNIT=<your_platform>

If you see compilation errors, check that your toolchain is configured correctly in ./build_system/units/Makefile.<your_platform> and consider whether you need to add custom linker or compilation flags for your OS or platform.

If all goes well, you should see a directory named install:

[sksam@toolchain1 samknows-sdk-generic-1.0.0]$ ll ./install/rpi3/
      total 8
      drwxrwxr-x 3 sksam sksam 4096 May 20 10:56 etc
      drwxrwxr-x 3 sksam sksam 4096 May 20 10:53 opt

This is the directory hierarchy that you should overlay onto the root of your firmware's filesystem at build time.

Note that the etc directory contains a single file: an init.d script that is used to start the SamKnows agent on the CPE. If your OS does do not use init scripts to start services, then create a new script accordingly.

Registering and activating your CPE

CPE will register automatically with the SamKnows backend when they come online. There is no need to first tell SamKnows that a CPE needs to be registered.

It may take up to one hour after a CPE is first switched on for it to download configuration from SamKnows. Subsequent boots will be almost instant.

To verify if your CPE has been able to register with the SamKnows backend, check to see if a SamKnows Unit ID is present on your device. On a CPE's shell, look for the file /tmp/samknows/tmp/samknows/unitid.

Test scheduling

Any CPEs that are auto-registered with SamKnows will be assigned with the default test schedule for this client (e.g. ACMECorp from the example earlier). In many cases, the default test schedule will be empty, meaning that no measurements run.

To configure a test schedule for your CPE or groups of CPE, please refer to the SamKnows One documentation. Test schedules will be applied within one hour of them being set in SamKnows One.

To inspect the current test schedule, run the following on the CPE:

root@rpi3-2c:dd:95:e3:02:64:~# crontab -l
      28 * * * * TZ=UTC '/tmp/ispmon'/scripts/base/sanity.sh >/dev/null 2>&1
      33 * * * * TZ=UTC '/tmp/ispmon'/scripts/base/timesync.sh >/dev/null 2>&1
      38 * * * * TZ=UTC '/tmp/ispmon'/scripts/base/submit_background.sh >/dev/null 2>&1
      28 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23 * * * TZ=UTC /tmp/samknows/scripts/cron/hourly
      43 1,4,7,10,13,16,19,22 * * * TZ=UTC /tmp/samknows/scripts/cron/once-every-3hours

The presence of entries such as /tmp/samknows/scripts/cron/hourly shows that measurements are configured to run on a regular basis.

Reference documentation for the measurement clients

Each measurement client has reference documentation included in the SDK. This details the parameters the client supports, the outputs it produces, the methodology of the test, and some example command line calls.

This documentation can all be found in ./<project_name>/README.md. For example:

[sksam@toolchain1 samknows-sdk-generic-1.0.0]$ find | grep README.md
      ./iplayer/README.md
      ./youtube-test/README.md
      ./README.md
      ./http_test/README.md
      ./udplatencyclient/README.md
      ./webget/README.md
      ./hulu/README.md
      ./cdn_client/README.md
      ./skpmontests/README.md
      ./online_storage_client/README.md
      ./jitter_client/README.md
      ./dns_client/README.md
      ./netflix/README.md

Release history

VersionDateDescription1.0.02018-05-20Initial release