Install

Hardio uses PID as its package/development management system. This section explains how to configure your projet to use hardio with PID.

How to configure a project that uses hardio

When creating a project that uses hardio, you will only have to depend on the correct IOBoard implementation and on each device you are using.

Let’s suppose we want to create a project named my_project that needs to use a hardio based software drivers. First of all create a PID workspace then create the package my_project (the url argument is recommended but optional if you did not create an online repository for your project):

cd /path/to/your/workspace
pid create package=my_project url=git@my_server.any:my/projects/my_project.git

Then edit the root CMakeLists.txt and fill it like this:

cmake_minimum_required(VERSION 3.19.8)
set(WORKSPACE_DIR ${CMAKE_SOURCE_DIR}/../.. CACHE PATH "root of the packages workspace directory")
list(APPEND CMAKE_MODULE_PATH ${WORKSPACE_DIR}/cmake) # using generic scripts/modules of the workspace
include(Package_Definition NO_POLICY_SCOPE)

PROJECT(my_project)

PID_Package(	
        AUTHOR          Your Name
        ADDRESS         git@my_server.any:my/projects/my_project.git
        YEAR 		2019
        LICENSE 	CeCILL
        DESCRIPTION	Say something
        VERSION         0.1.0
)

########### Core lib implementation ##################
PID_Dependency(hardiocore VERSION 2.0)
PID_Dependency(hardio-upboard VERSION 1.0)

################ Driver packages ########################
PID_Dependency(hardio_bno055 VERSION 3.0)
PID_Dependency(hardio_waterdetect VERSION 3.0)
PID_Dependency(hardio_ms5837 VERSION 3.0)
PID_Dependency(hardio_powerswitch VERSION 3.0)

# possibly other packages
...

build_PID_Package()

First of all, we want to implement a hardio based architecture so the project depends on the hardiocore project.
We want to develop a system on an intel Upboard so my_project depends on the hardio-upboard package that provides an implementation for Intel Upboards. Please note that the version of the framework in only defined by the version of hardiocore, here version 2.0. Other packages may have versions whose major number is not aligned with this version. For instance hardio-upboard version compatible with hardiocore version 2.0 or compatible is the 1.0.X.

All other dependencies list the device drivers for sensors and actuators used to implement my_project.

Now let’s talk about how one would declare a component (an application implementing your hardware architecture) in such a package. In my_project’s apps/CMakeLists.txt declare the application:

PID_Component(ms5837-test
        CXX_STANDARD 17
        DEPEND  hardio/ms5837
                hardio/upboard
                hardio/core
)

When declaring a component, you need to make it depend on the sensors it uses and the specific IOBoard those sensors are connected to, in this example the Upboard.

Now just by building the packages the required dependencies will be installed in your project PID workspace if needed, so in your project source folder you just have to launch the command:

pid build

To be short, the PID system automatically resolves and if needed installs dependencies of a PID project, so the hardiocore package for instance will be automatically deployed in your workspace if not already present.

How to configure a projet to implement a new IOBoard

When implementing a new IOBoard you basically need your project to depend on the hardiocore package. Then you will also need to use various protocols implementation that match your board specification. Let’s suppose your new board is a MRAA compatible board. MRAA is a project that provides a unififed interface for various embedded cards that share a common layout for IO pins. Among supported cards you can find Intel Upboards ans Raspberry Pi for instance. Also we consider this new board embded a Linux operating system.

cmake_minimum_required(VERSION 3.19.8)
set(WORKSPACE_DIR ${CMAKE_SOURCE_DIR}/../.. CACHE PATH "root of the packages workspace directory")
list(APPEND CMAKE_MODULE_PATH ${WORKSPACE_DIR}/cmake) # using generic scripts/modules of the workspace
include(Package_Definition NO_POLICY_SCOPE)

PROJECT(my_new_board)

PID_Package(	
        AUTHOR          Your Name
        ADDRESS         git@my_server.any:my/projects/my_new_board.git
        YEAR 		2019
        LICENSE 	CeCILL
        DESCRIPTION	A new board
        VERSION         0.1.0
)

PID_Dependency(hardiocore VERSION 2.0)

PID_Dependency(hardio-mraa VERSION 1.0)
PID_Dependency(hardio-linux VERSION 1.0)

build_PID_Package()

The principle is quite simple : each board needs to use the adequate protocols implementation, so the project needs to depend on two packages:

• hardio-mraa that provides protocols implementation for using MRAA boards pins : GPIO , PWM, etc.
• hardio-linux that provides protocols implementation for using linux/posix related services : IP/UDP/TCP protocol, serial communication, etc.

And to defne the library implementing the board(s):

PID_Component(my_super_board
        CXX_STANDARD 17
        EXPORT  hardio/core
                hardio/mraa
                hardio/linux
        )

Principle is the same as previously, but you should notice that the library uses the EXPORT argument for declaring component dependencies. This is because the headers of the dependencies will surely be included into your new library’s public headers. So dependencies declarations will transitively be available for any user of your library. The EXPORT keyword ensure the dependencies will be correctly managed by any component (application or library) using your library.

To install those dependencies, the principle is exacly the same as explained in previous section.

How to configure a project to create a new device or protocol

When creating a new device or a new protocol, the project depends on hardiocore and optionnaly any external library that is needed to implement device driver or protocol.

For instance, from CMake perspective :

cmake_minimum_required(VERSION 3.19.8)
set(WORKSPACE_DIR ${CMAKE_SOURCE_DIR}/../.. CACHE PATH "root of the packages workspace directory")
list(APPEND CMAKE_MODULE_PATH ${WORKSPACE_DIR}/cmake)
include(Package_Definition NO_POLICY_SCOPE)

PROJECT(my_new_device)

PID_Package(	
        AUTHOR          Your Name
        ADDRESS         git@my_server.any:my/projects/my_new_device.git
        YEAR 		2019
        LICENSE 	CeCILL
        DESCRIPTION	A new board
        VERSION         0.1.0
)

PID_Dependency(hardiocore VERSION 2.0)
PID_Dependency(tinyxml2 VERSION 8.0.0)

build_PID_Package()

Again the principles are exactly the same as previously explained. We suppose here that the package use the tinyxml2, for instance for parsing XML encoded messages that comes from the device.

The install follows the exact same logic as previously.

Then the library defining the new device driver could look like (in src/CMakeListst.txt):

PID_Component(my_super_device
        CXX_STANDARD 17
        EXPORT hardio/core
        DEPEND tinyxml2/tinyxml2
)

Here you can see that tinyxml2 library dependency is declared with the DEPEND keyword. This is not mandatory, but we recommend hiding as much as possible implementation details in your drivers code. So for instance we can use a pimpl idiom to avoid including tinyxml2 headers directly into the public headers of my_super_device: they will be rather included into my_super_device source code. Doing so we can declare tinyxml2/tinyxml2 component dependency using the DEPEND keyword (instead of using EXPORT).