Technical Details

• 1: Device detection
• 2: Module types
• 3: Packaging
• 3.1: Packaging guide

1 - Device detection

SDBP device detection

SDBP devices should be detected using the RESTful API.
Low-level detection is possible via /sys/class/sdbp/ path.

USB device detection

For plug & play detection of USB based modules the USB descriptors should be used.

The USB standard specifies that every device must register itself using a standardized generic descriptor.
This descriptor should be used to select the device driver.
The Linux tool “lsusb” or the sysfs path (e.g: /sys/bus/usb/devices/1-1/) can be used to access the descriptor fields.

The “idVendor” and “idProduct” fields contain identifiers which are typically set by the usb chip vendor and may be used for driver selection.
Some devices, such as usb-to-serial converters, are very application specific and cannot be selected reliable by using the idVendor/idProduct fields.
For these devices the USB specification allows the implementation of optional USB “manufacturer”, “product” and “serial” fields.

Modules with our firmware

Modules running our customized firmware must be selected using the “manufacturer”, “product” and “serial” fields.
The “manufacturer” field contains the manufacturer name (e.g: “NOREYA”) which should be used for filtering.
The “product” field contains the product name including the hardware version (e.g: “NEXUS HUB V04.01.01”) and must be used for selection and compatibility check.
The “serial” field is set on most devices and contains the serial number.

The specific module page should be checked for details.

Modules with third party firmware

Modules with third party firmware should be selected by “idVendor/idProduct” fields.
Some of them may also have the “manufacturer/product/serial” fields which should be preferred if available.

The specific module page should be checked for details.

How to query devices

Libudev

The recommended way of querying devices for selection is to use “libudev”.
There are several bindings (Python, Java, Rust…) available for the C-library.

It allows to pre-filter for specific device classes (e.g: serial devices) and supports device add/removal events.

The udev fields use different names for the descriptor fields:

Sysfs

If the “libudev” library cannot be used the Linux “sysfs” can be parsed.
The root entry point is “/sys/bus/usb/devices/”.

Example:

2 - Module types

Our modules are divided into USB and SDBP interface based devices:

Universal Serial Bus (USB)

Key features are:

• Support for USB 2.0 Low/Full/High speed modes
• Per-port power control
• Active over current sensing
• Advanced USB Descriptor fields for auto detection

Serial Device Bus Protocol (SDBP)

Key features are:

• Designed as open and reliable protocol for low level devices
• Dynamic speed configuration up to 16MBit/s
• Up to 1200 transactions/second from userspace
• Real-time communication support
• Standardized device detection via descriptor (like USB)
• GPLv2 based Linux kernel driver

3 - Packaging

Target

If you are a maintainer of an interesting project that should be available on our platform we would like to provide it from our package repository.
It is possible to provide packages by a self hosted personal package archives (PPA) but we will not guarantee compatibility in this case.

Basic ideas

1. The package must be maintainable. Concepts like installation/removal/purge/upgrade must be considered.
2. The platform is an embedded device, we do want to keep the resource as low as possible.

Requirements

• The source code must be located in Github, Gitlab or any other public repository.
• The project must be actively maintained.
• If the package is designed as service it must use/support systemd.
• If you do not have experience in packaging Debian archives we recommend to use our script based template [TODO: Link].
• The package must be provided in “.deb” Debian archive format.
  • The package should be build against the libraries in our repository.
    • If the package requires additional or newer libs they should be provided as separate package.
    • Static builds require an explicit statement why this is needed.
  • The package must be support clean installation, upgrade and removal.
  • The package must define all dependencies and incompatibilities (in the .deb conf file).
  • The package is not allowed to change core libs or system configuration files.
• Environment specific notes:
  • Python packages:
    • The installation of python packages via “pip” or similar tools is forbidden.
    • The packages from our repository (python3-*) should be used, we can easily provide missing packages from pypi.org on request.
    • If there are good technical reasons the package may use a virtual environment. It must be created on installation and removed on removal.
  • Java packages:
    • Java packages should use the installed runtime.
  • Docker containers:
    • Docker containers can be used but are not recommended due to the overhead and maintenance problems.
      • They must be packed in a Debian archive (docker save) and support installation/removal/upgrade to avoid “pollution” of the system by unused/deprecated containers [TODO: Add guide].

3.1 - Packaging guide

To build Debian packages for our platform the following information is important:

• We use the official Debian build tools for packaging. The following dependencies must be installed before building:
  sudo apt-get install devscripts quilt chrpath git wget apt-utils debhelper
  Depending on the project, there may be more dependencies.
• The official Debian packaging process is (historically) complicated.
  To simplify the package build configuration we use a single script.
  Each project contains a makedeb.sh file which generates the package content and metadata on execution.
  All configs are in this file and on execution the directory builddeb is created which contains the build data and the resulting debian archive file.
• The script’s workflow looks like this:
  • Declare build variables
  • Create an empty builddeb directory
  • Copy all the relevant files from the project to a virtual root structure under builddeb/
  • Generate the Debian archive metadata
  • Generate the install/removal/upgrade files
  • Build the package
• Architecture dependent projects (C/C++, Rust…) usually need to build the executable/library before the script is called.
• The packages must be built with the official image (root filesystem) and its dependencies.
  The image/rootfs can run on real hardware or be emulated.
  Package-cross-builds from other architectures (x86, amd64) or distributions (Ubuntu) are not possible!
  This refers only to the packaging, but cross-compilation of the binaries is recommended.

Example

This must be executed on the Nexus:

• sudo apt-get install devscripts quilt chrpath git wget apt-utils debhelper
• git clone https://github.com/noreya-nexus/PROJECT
• Follow the project build steps (Note: Building projects can take very long!)
• ./makedeb.sh
• ls -l builddeb/*.deb