Conreality DDK for Python

This chapter describes the Conreality driver development kit (DDK) for the Python programming language.

The Python language is one of the established lingua francas of modern programming, and the Python DDK is intended to enable the largest possible developer audience to contribute to the development of Conreality drivers.

The Python ecosystem affords drivers access to much great software such as, to name just a few examples: ROS, OpenCV, scikit-image, scikit-learn, TensorFlow, NuPIC, NLTK, and spaCy. Further, there tend to be no shortage of Python libraries, tutorials, and examples available for popular single-board computer platforms such as the Raspberry Pi.

Installation

The Conreality DDK for Python supports POSIX platforms and requires the following prerequisites on the development and target systems:

$ sudo apt install python3-pip
$ sudo apt install python3-numpy
$ sudo apt install python3-opencv # after Ubuntu 16.04

$ sudo pip3 install lupa
$ sudo pip3 install numpy             # only if python3-numpy not available
$ sudo pip3 install scandir           # not needed for Python 3.5+
$ sudo pip3 install cython            # optional

Introduction

The Python DDK is built around the asynchronous I/O facilities in Python 3 (the asyncio package in the standard library).

Each Python driver runs an asyncio event loop, waiting for events of interest. The driver process will typically be sleeping most of the time, only waking up when there is a state change on one of the monitored file descriptors. The event loop registers file descriptors to be monitored with the operating system kernel, enabling power-efficient waiting without a busy loop.

Tutorial

(To be written.)

from conreality import ddk

Defining the Driver Event Loop

(To be written.)

class MyDriver(ddk.Driver):
  def init(self):
    pass # TODO

  def exit(self):
    pass # TODO

  def loop(self):
    pass # TODO

Parsing Command-Line Arguments

(To be written.)

class MyArgumentParser(ddk.ArgumentParser):
  def init(self):
    self.add_argument('id', nargs='?', default='default',
      help='the ID of the camera to attach to')
    self.add_argument('-r', '--fps', type=int, default=30,
      help='set the frames per second (FPS) rate (default: 30)')
if __name__ == '__main__':
  import sys
  with MyDriver(argparser=MyArgumentParser) as driver:
    sys.exit(driver.run())

Reference

(To be written.)

Module conreality.ddk.camera

This module contains support code for generic camera APIs.

class conreality.ddk.camera.CameraRegistry
class conreality.ddk.camera.CameraDirectory(id)
class conreality.ddk.camera.CameraFeed(dir)

Module conreality.ddk.driver

This module contains support code for implementing driver programs.

class conreality.ddk.driver.Logger

Mixin that implements logging to the system log.

Logger.open(verbosity=syslog.LOG_NOTICE)

Opens the connection to the system log.

Logger.close()

Closes the connection to the system log.

Logger.log(priority, message, *args)

Logs a message to the system log (typically, /var/log/syslog).

Returns:self
Return type:Logger
Logger.panic(message, *args)

Logs a message to the system log with LOG_EMERG priority.

Returns:self
Return type:Logger
Logger.alert(message, *args)

Logs a message to the system log with LOG_ALERT priority.

Returns:self
Return type:Logger
Logger.critical(message, *args)

Logs a message to the system log with LOG_CRIT priority.

Returns:self
Return type:Logger
Logger.error(message, *args)

Logs a message to the system log with LOG_ERR priority.

Returns:self
Return type:Logger
Logger.warning(message, *args)

Logs a message to the system log with LOG_WARNING priority.

Returns:self
Return type:Logger
Logger.notice(message, *args)

Logs a message to the system log with LOG_NOTICE priority.

Returns:self
Return type:Logger
Logger.info(message, *args)

Logs a message to the system log with LOG_INFO priority.

Returns:self
Return type:Logger
Logger.debug(message, *args)

Logs a message to the system log with LOG_DEBUG priority.

Returns:self
Return type:Logger
class conreality.ddk.driver.Driver(argv=sys.argv, argparser=ArgumentParser, input=sys.stdin, output=sys.stdout)
Driver.init()

Executed on initialization of the driver process. Override this in your subclass.

Driver.exit()

Executed on termination of the driver process. Override this in your subclass.

Driver.loop()

Executed on each tick of the driver event loop. Override this in your subclass.

Driver.stop()

Stops the driver event loop, terminating the driver process.

class conreality.ddk.driver.ArgumentParser

The default implementation of command-line argument parsing.

class conreality.ddk.driver.DataDirectory(*path)
exception conreality.ddk.driver.DataDirectoryException(error)

Module conreality.ddk.sysexits

This module contains constants for the standard exit codes that driver programs should use to indicate their termination status.

EX_OK = 0 # successful termination
EX_USAGE = 64 # command line usage error
EX_DATAERR = 65 # data format error
EX_NOINPUT = 66 # cannot open input
EX_NOUSER = 67 # addressee unknown
EX_NOHOST = 68 # host name unknown
EX_UNAVAILABLE = 69 # service unavailable
EX_SOFTWARE = 70 # internal software error
EX_OSERR = 71 # system error (e.g., can't fork)
EX_OSFILE = 72 # critical OS file missing
EX_CANTCREAT = 73 # can't create (user) output file
EX_IOERR = 74 # input/output error
EX_TEMPFAIL = 75 # temp failure; user is invited to retry
EX_PROTOCOL = 76 # remote error in protocol
EX_NOPERM = 77 # permission denied
EX_CONFIG = 78 # configuration error

Module conreality.sdk.storage

class conreality.sdk.storage.DataDirectory(*path)
exception conreality.sdk.storage.DataDirectoryException(error)