Hardware interfaces

Hardware IO (input/output) interfaces, including the serial-port, gpio and i2c interfaces, are designed to be used on devices running Ubuntu Core. These interfaces are exposed as slots from a device’s gadget snap which is used to define and configure a device’s system properties.

This approach is more robust because it allows the gadget snap providing the slot to centralise and arbitrate the connection conditions. These conditions include which other snaps, identified by their snap ID, can connect to the slots the gadget offers and, consequently, gain privileged access to the hardware. For the application snap, usually no change is required other than to declare and use an appropriately-configured plug.

See Supported interfaces for a complete list of interfaces.

Interface considerations

The extent of access an interface has is granted through both connection permissions and the specifics of the interface connections being requested.

  1. Connection permissions: auto-connect | privileged | super-privileged
    Connection requirements are dependent on which store a developer is using.
    • Global Snap Store: privileged and super-privileged interfaces require store approval because of the level of trust and permissiveness these interfaces have, which is also why certain interfaces need certain oversight. See Permission requests for further details.
    • Dedicated Snap Store: trust and permissiveness are now the responsibility of the store owner, and many privileged interface connections can be self-served and defined within the dedicated snap store and the device context.
  2. Interface connections: hardware IO interfaces | app-provided interfaces | other interfaces
    • Hardware IO interfaces: These require either a slot to be defined by a device’s gadget snap or an interface with Hotplug support, in which case the slot appears from the system snap.
      • An unconstrained auto-connection cannot be used because there may be many slots of a given interface, resulting in ambiguity that requires an extensive set of store rules to manage and maintain.
      • Each plug should therefore be connected to a slot, for example:
        • green led plug on app => green led slot on gadget
        • red led plug on app => red led slot on gadget
    • App-provided interfaces: slots are defined by apps, or occasionally from the gadget snap,
    • Other interfaces: For more system level access, slots are provided by the system snap.

Code examples

The gadget snap definition for the reference Raspberry Pi Ubuntu Core image contains interface definitions for various hardware IO interfaces on the system, including slots for each specific GPIO pin, i2c connections, the Bluetooth serial port, and the generic serial ports:

slots:
  bcm-gpio-0:
    interface: gpio
    number: 0
  bcm-gpio-1:
    interface: gpio
    number: 1
  bcm-gpio-2:
    interface: gpio
    number: 2
[...]
  i2c-0:
    interface: i2c
    path: /dev/i2c-0
[...]
  bt-serial:
    interface: serial-port
    path: /dev/ttyAMA0
[...]
  serial0:
    interface: serial-port
    path: /dev/ttyS0
  serial1:
    interface: serial-port
    path: /dev/ttyS1

On a Raspberry Pi, the above hardware IO interfaces are accessible to apps from the system snap without requiring any further configuration.

Interface list

Interface Description Categories Auto-connect
device-buttons use any device-buttons Hardware, Developer no
dsp enables the control of digital signal processors (DSPs) Hardware, Developer no
dvb allows access to all DVB devices and APIs Hardware, Developer, Media no
fpga permits access to an FPGA subsystem Hardware, Developer no
framebuffer access to universal framebuffer devices Hardware, Developer no
gpio access specific GPIO pins GPIO, Hardware, Developer no
gpio-memory-control allows write access to all GPIO memory GPIO, Hardware, Developer no
hardware-observe access hardware information System, Hardware no
hardware-random-control provide entropy to hardware random number generator System, Hardware no
hardware-random-observe use hardware-generated random numbers System, Hardware no
i2c access i²c devices System, Hardware no
iio access IIO devices System, Hardware no
joystick use any connected joystick Hardware, Developer no
media-control access media control devices and Video4Linux (V4L) devices Hardware, Developer, Media, Video no
optical-drive read/write access to CD/DVD drives Storage, Hardware, Developer yes, unless drive can write
pwm access specific PWM channels System, Developer, Hardware, WIP no
raw-input access raw input devices directly System, Developer, Hardware no
raw-usb access USB hardware directly System, Developer, Hardware no
serial-port access serial port hardware System, Developer, Hardware no by default, yes with snaps from the same publisher
spi access specific SPI devices System, Developer, Hardware no
u2f-devices use any U2F devices Security, Hardware, Developer no
uhid create kernel UID devices from user-space Hardware, Kernel, System no
uinput allows write access to /dev/uinput Super privileged, Hardware no
uio access uio devices Hardware, System no
  • Each plug should therefore be connected to a slot, for example:
    • green led plug on app => green led slot on gadget
    • red led plug on app => red led slot on gadget

I would add:

This kind of 1-to-1 connections can usually be established via slot rules in the snap-declaration for the gadget.

Great, thank you for looking over this, and for the suggestion!

wouldn’t “are introduce via slots” or “are exposed as slots” instead be a bit more specific? and prepare for the mention of slot in the 2nd paragraph?

Thanks for the suggestion. I’ve updated the text.