Additional Topics

Modules

Modules are essentially plug-ins for Extensions. They provide a way of defining common and reusable functionality. An Extension can load zero or more modules during its creation. Loaded modules will then add their capabilities (see Capabilities) to those of the Extension. When calling code tries to access an attribute of an Extension the Extension doesn’t have, it will try to find the attribute among its loaded modules and will return that instead.

Note

Modules are themselves extensions, and can therefore load their own modules. Do not abuse this.

For example, calling code may wish to reboot an unresponsive device by calling device.hard_reset(), but the Device in question does not have a hard_reset method; however the Device has loaded netio_switch module which allows to disable power supply over a network (say this device is in a rack and is powered through such a switch). The module has reset_power capability (see Capabilities below) and so implements hard_reset. This will get invoked when device.hard_rest() is called.

Note

Modules can only extend Extensions with new attributes; they cannot override existing functionality. In the example above, if the Device has implemented hard_reset() itself, then that will get invoked irrespective of which modules it has loaded.

If two loaded modules have the same capability or implement the same method, then the last module to be loaded “wins” and its method will be invoke, effectively overriding the module that was loaded previously.

Specifying Modules

Modules get loaded when an Extension is instantiated by the extension loader. There are two ways to specify which modules should be loaded for a device.

Capabilities

Capabilities define the functionality that is implemented by an Extension, either within the Extension itself or through loadable modules. A capability is just a label, but there is an implied contract. When an Extension claims to have a particular capability, it promises to expose a particular set of functionality through a predefined interface.

Currently used capabilities are described below.

Note

Since capabilities are basically random strings, the user can always define their own; and it is then up to the user to define, enforce and document the contract associated with their capability. Below, are the “standard” capabilities used in WA.

Note

The method signatures in the descriptions below show the calling signature (i.e. they’re omitting the initial self parameter).

active_cooling

Intended to be used by devices and device modules, this capability implies that the device implements a controllable active cooling solution (e.g. a programmable fan). The device/module must implement the following methods:

start_active_cooling()
Active cooling is started (e.g. the fan is turned on)
stop_active_cooling()
Active cooling is stopped (e.g. the fan is turned off)

reset_power

Intended to be used by devices and device modules, this capability implies that the device is capable of performing a hard reset by toggling power. The device/module must implement the following method:

hard_reset()
The device is restarted. This method cannot rely on the device being responsive and must work even if the software on the device has crashed.

flash

Intended to be used by devices and device modules, this capability implies that the device can be flashed with new images. The device/module must implement the following method:

flash(image_bundle=None, images=None)
image_bundle is a path to a “bundle” (e.g. a tarball) that contains all the images to be flashed. Which images go where must also be defined within the bundle. images is a dict mapping image destination (e.g. partition name) to the path to that specific image. Both image_bundle and images may be specified at the same time. If there is overlap between the two, images wins and its contents will be flashed in preference to the image_bundle.