Drivers

What are MaCI drivers?

MaCI drivers are abstractions over hardware devices. Drivers are divided in two classes: Bus and Device drivers. Bus drivers are for unified access over standard busses, like serial, I2C or CAN. Device drivers use Busses for accessing hardware and provide higher level control over it. MaCI drivers are written as standalone drivers so they can also be used outside MaCI if required.

Creating Bus and Device Drivers

All MaCI driver implementations should follow a few general guidelines:

  • Unique and descriptive naming
Driver sources should be placed in subdirectory which corresponds to the type of driver in case and its sources/headers should be named likewise. (No generic filenames such as 'driver.h' or 'interface.h' should exists in the source-tree)
  • Run-time configuration
Driver interfaces should be written so that they are fully configurable without using compile-time parameters. For example; Serial port Bus driver should not make any assumptions about the device path or speed settings.
  • Unified style interfaces
There is no explicit rule about functions required for any specific driver. However, all drivers should have some kind of Open() and Close() function which also preferably have some knowledge about the existence of the underlying hardware. (For example; SICK laser-scanner driver will return failure for Open() if the device doesn't reply as it should)
  • Standalone test software
All drivers should include a local Makefile and provide some kind of quick-testing program for the device. For example, the SICK laser-scanner has a testing tool which is able to configure and use the device over command line interface. At least some kind of 'usage example' for the drivers features should be provided. (Often examples are more useful than documentation - especially incomplete documentation)
  • Namespacing
Drivers and Busses can be inside any namespace wanted. However, please be careful not to use too generic function or variable names in the global namespace. For example, defining a variable 'x' in the global namespace is probably not a good idea. If you want your driver to be part of MaCI namespace, you can place your driver in MaCI::Drivers namespace.
  • Documentation
All interfaces MUST be documented using the Doxygen format. Running 'make doc-all' at top level of MaCI will attempt to generate the documentation. If your piece of software emits any Doxygen warnings, PLEASE fix them before your final release. Poorly documented drivers/interfaces will probably be rewritten when somebody wanting to use them doesn't understand how they work.
  • Something else
Is there something important/good-to-know about creating drivers? Do you have questions that you think this documentation should answer? Then please add a placeholder here or direct your questions directly to the developers (Contact information can be found from the Feedback page).

Bus drivers

Bus drivers abstract different hardware interface methods. (CAN, I2C, Serial, TCP, etc.) Bus drivers mainly exists to provide Device driver developers a more convenient methods for accessing hardware. Because bus drivers should be used by all devices, they can be implemented to support 'medium sharing'.

Bus drivers are located under directory "MaCI/bus". If you have an implementation of a Bus driver, just create a directory for it (keeping the general rule #1 in mind) and import your driver sources in there.

Device drivers

When starting to implement a new driver the user should check:

  • Is there a driver already implemented for the device
  • Is there a Bus driver available that this device driver could use
  • If there is no suitable Bus driver available, would it be useful to implement the Bus driver as a shared MaCI Bus driver so others wouldn't have to rewrite it in the future (instead of writing the bus communication code directly in the device driver)

If these checks have been made and all appropriate actions taken, proceed to create a driver according to the general instructions.

Device drivers are located under directory "MaCI/drivers".

Using Bus and Device Drivers ...

Is easy! Just do it!

Bus drivers

Include and link directly.

Device drivers

Include and link directly.