CommunicationModule

Documentation Status

The CommunicationModule is a library aimed at 8bit-avr microcontrollers. The intent is to offer software support for several 802.15.4 based network chips like MRF24J40MA or the XBee. To allow interaction with these chips a drivers for the respective peripheral interface (USART, SPI) are included.

Dependencies

The library comes with very few but essential dependencies. To use the precompiled library you’ll need

  1. avr-gcc

  2. CException

  3. Mutex

  4. PeripheralInterface

To use our build scripts you will have to install the Bazel build tool. You can find install instructions at https://docs.bazel.build/versions/0.26.0/install.html.

We recommend using the BazelCProjectCreator script to create your project. Additionally to the dependencies already present in the WORKSPACE file you will need to add the following lines:

http_archive(
    name = "EmbeddedUtilities",
    strip_prefix = "EmbeddedUtil-0.3",
    urls = ["https://github.com/es-ude/EmbeddedEmbeddedUtilities/archive/v0.3.tar.gz"],
)

http_archive(
    name = "PeripheralInterface",
    strip_prefix = "PeripheralInterface-0.6",
    urls = ["https://github.com/es-ude/PeripheralInterface/archive/v0.6.tar.gz"],
)

http_archive(
    name = "CommunicationModule",
    strip_prefix = "CommunicationLibrary-0.1.5",
    urls = ["https://github.com/es-ude/CommunicationLibrary/archive/v0.1.5.tar.gz"],
)

Alternatively you can copy the dependencies from WORKSPACE file in this project and add the CommunicationModule dependency (as shown above).

How to use the library

The library follows a strict separation of interfaces and implementation. Several different implementations of each interface may be in use at the same time (however keep in mind not to use the same physical ressource more than once). All implementation is hidden behind abstract data types. To start using a module you have to create the corresponding structs. To give users as much control over their memory usage as possible, every implementation offers two functions

  1. size_t InterfaceNameImplementationName_getADTSize(void);

  2. InterfaceName InterfaceName_create(InterfaceName ptr_to_memory, OptionalConfigParameters parameters);

The create function usually also initializes the implementation, so that after calling it you can start using the implementation. For details about functions offered by the interfaces see their doxygen documentation or take a look at their header files.

IMPORTANT: To use the library you will have to implement the executeAtomically() function. This is necessary to make the Mutex lib work. The corresponding header file can be found in the EmbeddedUtilities repo under EmbeddedUtilities/Atomic.h.

Predefined setups for the department’s platforms

A ready to use setup for the Motherboard and ElasticNode hardware platforms is available. To compile these use the following command:

bazel build integration_tests:HardwareSetup --platforms @AvrToolchain//platforms:Motherboard

or:

bazel build integration_tests:HardwareSetup --platforms @AvrToolchain//platforms:ElasticNode

respectively.

How to use the setups in your own bazel project

Integrate e.g. the MotherboardSetup lib like so:

default_embedded_binary(
    name = "MyApp",
    srcrs = ["src/MyApp.c"],
    deps =  ["@CommunicationModule//Setup:MotherboardSetup"],
)

Exceptions

Instead of passing and handling error codes in long if-else statements, we use the CException library. However currently it is only partially used.

Known Issues

  • non blocking functions are in development

  • enabling promiscuous mode seems to prevent back to back reception of packages