Universal Serial Bus (USB)

Universal Serial Bus is an industry standard currently used to connect peripherals to computer and other devices. This includes range of devices from keyboard, pointing devices, disk drives to printers, network adapters and few more. The usage not restricted to connectivity but also that to power the devices(most phones, PDA, tablets,video game consoles) with the same standard USB ORG. USB standard is also being used as interface for storage device and for devices with serial interface.

Device type and classes and connectors

With wide range of device classes defined by class codes to communicate with the USB host, we have human interface dvice, mass storage, wireless controllers, audio video interface, etc. While devices classes are one aspect of dividing the usb based on usage, we also have wide variety of connectors.
Some of the common usb connectors are

• Type A & Type B (Standard)
• Type A super speed & Type B super speed.
• Mini A & Mini B
• Micro A & Micro
• Type C

USB Specifications has moved from the initial phase of USB1.0 to USB2.0, and ready to be transitioned to much more advanced USB3.0

USB as Storage Device in IOx

With the growing number of devices having USB interface, it brings with itself plethora of options to extend IOx features. One such feature is having USB as mass storage supplementing the built in system storage.

Using USB flash drive to supplement the storage for IOx opens up the platform to developer to come up with applications which requires more storage.

As such, USB A port in IR829, which supports USB2.0, enables developer of IOx apps to rely on the underlying CAF to provide the benefits of USB mass storage when a suitable flash drive is plugged in.

Caveats and Limitations

• USB with one partition is supported currently
• External USB hub is not supported as of now.
• Flash drives which are formatted already with VFAT file system is supported.(with support extended to other types in future releases)
• Any disk based storage device hasnt been tested. (only those with pen drive which doesnt require external power will be supported currently)
• USB2.0 compliant type A device is supported
• Hot swapout and swap in are not supported. USB should be plugged in, before the application is installed on to the IOx box.
• Support is provided for Application Types such as Docker, Lxc, and PAAS style apps.

USB as Serial Device in IOx

We support interfacing serial devices with USB along with those on board serial interfaces(like RS232, RS485). As such, USB A port in IR829, which supports USB2.0, helps us to connect any serial devices which has USB interface.

Caveats and Limitations

• External USB hub is not supported as of now.
• USB2.0 compliant type A device is supported
• Hot swapout and swap in are not supported. USB should be plugged in, before the application is installed on to the IOx box.
• Support is provided for Application Types such as Docker, Lxc, and PAAS style apps.

The flow diagram below illustrate the presence of USB and its selection.

.

Pre-requisites for the application.

The usb device details are passed in application.yaml. At the time of app activation,the payload is passed in two ways

• through the browser using LocationManager(LM)(as in below diagram) or
• through the ioxclient with the payload as specified in the sample above.

Device selection in LM:

Any attached devices to the routers/hosts are detected by usb controller in the host and notifies to the CAF with its details collected in the device_lists. The device list is checked for any "usb_interfaces" to be used for Mass storage.

If the application queries for storage devices in the payload and specifies it as mandatory yes/no(in the package.yaml), then any available USB device is allocated and mounted by the host. This is later exposed to the guest in their root file system.

Packaging structure and format

The sample yaml is being provided to use with the app.USB Usage & Code

Some of the fields are optional while others are mandatory.

'type' :is mandatory field and is usbdev for usb type of devices 'serial' for serial devices

'label': is mandatory field used to recognize the mount point in the container for the USB device and accessible through environment variable with echo

'usage': is an optional field as a description of the device usage

'function': is a mandatory field used for describing the usb as 'storage' or 'serial'

'mandatory': is an optional field used to describe whether the device is mandatory for the app to get activated or not.

'mount-point' : is optional field where the developer can specify where exactly the USB should be mounted in the container. Ex: /extra/storage is the mount point specified in the yaml, hence the USB is available at that location, else the default location can be found from the label field.

'device-directory-to-mount': is optional field where if the user want specific director inside the USB to be mounted in the container. Ex. the USB will have directory /usbdata which has to be mounted directly to the mount point above.

'vendorID/productID' : these fields are optional. But when specified, should contain both vendorID/ProductID to correctly identify the device that has to be used. If the device specified is not free/available, the user can select a different device from the available devices.

• The field mandatory should be specified as "True"/"yes" for application which requires USB, without which it wont get it to work.

• For applications, where having USB device is a option rather than a requirement, the field can be set to "False"/"no" .

Note: Fields "mount-point", "device-directory-to-mount" is specific to storage device.

• Applications which doesnt require USB, need not have the code snipppet for the devices in their package.yaml

Copy...
devices:
  -  
    type: usbdev
    label: HOST_DEVLXC
    usage: This is a mandatory flash drive for LXC app
    function: storage
    mandatory: yes
    mount-point: /extra/storage/
    device-directory-to-mount: /usbdata
    vendorID: "0451"
    productID: "8027"
....

Sample Application Yaml

Copydescriptor-schema-version: "2.4"

info:
  name: nt01-python_simple
  description: "Simple Python Application"
  version: "0.1"
  author-link: "http://www.cisco.com"
  author-name: "Cisco Systems"

app:
  type: lxc
  cpuarch: x86_64
  kernel-version: "4.4"

  resources:
    profile: custom
    cpu: 500
    memory: 64
    disk: 2

    network:
      -  
        interface-name: eth0
    devices:
      -  
        type: usbdev
        label: HOST_DEVLXC
        usage: This is a mandatory flash drive for LXC app
        function: storage
        mandatory: yes
        mount-point: /extra/storage/
        device-directory-to-mount: /usbdata
        vendorID: "0451"
        productID: "8027"

  # Specify runtime and startup
  startup:
    rootfs: app.ext2
    target: /sbin/init

App Payload

Copy{
    "resources": {
        "profile": "custom",
        "cpu": "25",
        "memory": "50",
        "disk": "100",
        "network": [{"interface-name": "eth0", "network-name": "iox-bridge0"}],
        "devices": [{"type": "usbdev", "label": "HOST_DEVLXC", "device-id": "/dev/bus/usb/001/027", "vid":"0451", "pid":"8027"}]    }
}