Application Hosting on Cisco Catalyst Access Points

Create an IOx Application Package

To create the IOx application, you will need to package the Docker image as an IOx application.

Prepare the Package Descriptor File (package.yaml)

The IOx package descriptor is a mandatory file describing the resource requirements and metadata about the IOx application.

The package descriptor file should meet the following requirements:

  • It should be a valid YAML file.
  • It must be named package.yaml.
  • It should be present in the root of the package.

For details, refer to the IOx application package documentation.

Sample package.yaml files are available at https://github.com/CiscoIOx/artifacts/tree/master/package_descriptor/samples/.

package.yaml
Copy
$ cat package.yaml
descriptor-schema-version: "2.10"

info:

  name: Sample_hello_world_app

  description: "Simple Hello World Application"

  version: "1.0"

  author-link: "http://www.cisco.com"

  author-name: "Cisco Systems"

app:


 # Refer Platform Support Matrix table.
 # armv7l for 32 bit CPU Architecture.
 # aarch64 for 64 bit CPU Architecture.
  cpuarch: armv7l
  type: docker # Indicate app type (docker)

  resources:
    profile: c1.small
    devices:
    - type: serial
      label: HOST_DEV
      alias: usb
      usage: serial device of usb dongle connected to ap.
    network:
      -   
        interface-name: eth0
        ports:
            tcp:
            - 8000
            - 8001
            udp:
            - 8000
            - 8001

# Specify runtime and startup

  startup:
    rootfs: rootfs.img
    target: /bin/sh

Details of the package descriptor file (package.yaml) are listed below :

  • Descriptor schema version 2.10 is supported.
    The schema version defines the rules associated with the descriptor file. Other schema versions that are supported and their corresponding rules can be found here.
  • In the info section, you can specify the IOx app name, app description, app version, and app owner.
  • In the app section, you can indicate the CPU architecture and type of the app. The cpuarch can either be armv7l or aarch64. To find out the CPU architecture, see the Supported Access Points Resources Matrix.
  • In the type field, specify type as docker.
  • In the Resources section, specify the memory, storage, CPU, network, and serial device required by the app. This is explained in detail below.
  • In the Startup section for the target, specify the binary that you need to run as part of the IOx container.

CPU and Memory Requested by IOx App

Refer to the Supported Access Points Resources Matrix to determine available memory for IOx apps depending on your AP model. As an app developer, you can use the default profiles "c1.tiny", "c1.small", and "custom".

For a custom profile, it is mandatory to specify the required CPU, memory (run-time memory), and disk space (flash). Refer to the below template for the format of the package.yaml file. If the required CPU, memory, or disk space exceed the available resources at run time, it will result in failure to deploy the IOx application. Kernel cgroups for IOx apps have been configured to consume only upto 25% CPU for all applications running on the AP.

  • Specify CPU<= 500 per app.
    CPU units are obsolete. However, for backward compatibility, the CPU entry must be present in the package.yaml file.
  • Memory: Run-time RAM requirement.
    If the memory consumption exceeds allocated memory, the app will restart.
  • Disk: Persistent storage required to run this app.
    If the app consumes more disk space, the persistent storage requirement of the host will be impacted.
  • For resource availability depending on the access point, refer to the Supported Access Points Resources Matrix.

Storage of IOx app needs to be used very sparingly and less frequently by IOx apps. More frequent usage of persistent storage by IOx app will lead to wearing out of flash storage on AP. Logs can be stored in /data/logs directory, but it should be disabled by default. IOx apps bootstrapping facility (https://developer.cisco.com/docs/iox/#!application-development-concepts/application-development-concepts) can be used to change the debug and debug level setting. only when debug is enabled logs can be stored in /data/logs at debug_level. This way debug settings can be enabled from DNAc when debug needs to be done on the IOx app. Also logs can be dumped to /data/logs only when certain error conditions are detected in the IOx app.

Resources Section of the Package Descriptor File (package.yaml)

Code Snippet
Copyresources:
    profile: custom
    cpu: 500
    memory: 96
    disk: 5
Profile Memory CPU
c1.tiny 32 100
c1.small 64 200

Network Interfaces and Network Ports Requested by IOx App

In the resource section of the package descriptor file, you can request a network interface as well as network ports required for the IOx app as shown below:

Code Snippet
Copynetwork:
      -   
        interface-name: eth0
        ports:
            tcp:
            - 8000
            - 8001
            udp:
            - 8000
            - 8001

Note:
Ports are required only if the IOx app needs incoming connections. For outgoing connections, ports are not required.

Access AP's Internal USB interface

Cisco Catalyst 9100 Family of Access Points support IOT functionality through a serial device interface. Refer to the Supported Access Points Resources Matrix to check if your AP supports USB for IOx apps.

The IOx app can request the serial device plugged into the USB port by specifying it in the devices section of the package descriptor file using the alias field as below.
Currently, the AP supports three USB serial device drivers, they are: cp210x, cdc_acm, and ftdi_sio.
In the devices section, add:

  • alias: usb_serial: If the USB dongle uses cp210x or ftdi_sio device driver
  • alias: usb_modem: If the USB dongle uses cdc_acm device driver

    Note: The alias field value is case sensitive.

Code Snippet
Copydevices:
      -  
        type: serial
        label: HOST_DEV
        usage: IOT functionality through serial device
        alias: usb_serial
        mandatory: yes

Please refer to the FAQ section for more information.

Once the IOx app is installed on the access point, the IOx application can get the name of the IOT serial device by sourcing the env variable as below:

Note: The name of the env variable will be the same as the value of the label field opackage descriptor. In the above example, it is HOST_DEV.

From inside the example IOx app:

Code Snippet
Copy/ # cat /data/.env
#!/bin/sh
export HOST_DEV=/dev/USB0
/ #
/ #
/ # source /data/.env
/ # env
APA03D:/# env
HOST_DEV=/dev/USB0

Create package.tar

Once the IOx app package descriptor file (package.yaml) is ready, the ioxclient can be used to create an IOx app for the access point as below:

Code Snippet
Copy$ cd xx-app
$ mkdir conf
$ # copy package.yaml created in previous step to conf directory
$ sudo ioxclient docker package -p ext2 -r 5 iox-hello-xx ./conf 
$ ls conf/
package.tar package.yaml

Note: While creating the IOx package for APs, you need to specify the -p ext2 option using the above ioxclient command. If this is not specified while creating the IOx package, you might experience application installation failure on the AP.

Your IOx app package (package.tar) is ready.

Next