CreatingNull / Null-Packet-Comms-Arduino

A library for wrapping the arduino UART serial in a binary packet based communication protocol.

Arduino Null Packet Comms

This is an arduino library that implements a binary packet-based communication protocol on top of the arduino Serial library. This wrapper allows for robust generic data transfer between systems, it is heavily relied on for the Arduino UOS implementation.

For details on this implementation and the API, see the project documentation. For more information on the NPC protocol and its uses, please see the protocol documentation.

---

Getting Started

This project is stand-alone and the only requirement is for it to be used in arduino projects.

Installation

The recommended method to use this library is downloading the latest stable release from the registry using the Arduino Library Manager.

Using the arduino-cli:

arduino-cli lib install NullPacketComms

Using the arduino-ide:

Pre-packed zipped versions of the latest builds can also be obtained from the GitHub build artifacts. Alternatively, you could manually pack the source and add the library manually, see instructions.

Usage

This library handles communicating and verifying data between the primary and remote device, what you do with that data is up to you. In the simple_example sketch, we implement a simple accumulating calculator on the arduino that can handle addition or subtraction operations.

This example sets the:

• target_ - Target address is used to define the operation.

  • 10 - Perform an addition operation
  • 11 - Perform a subtraction operation
  • 12 - Return the current accumulator value as a signed 16-bit integer.

• payload - 1 byte unsigned integer to add or subtract.

Using a NPC connection in this manner is implemented in a similar manner to if you were using raw UART, however instead of using manual read and write commands we use readPacket and writePacket. The benefit is that we get a closed loop communication where commands are acknowledged, checksums are verified, and both the primary and the remote have some confidence in what is being sent and received.

For more information on the API see the library documentation.

Source Structure

The source code is written in C++ and contained within the src/ subdir. The source code is formatted using clang-format specifications. This is automated via the pre-commit framework, see repo hooks. The hook's arduino-lint dependencies should be installed for the OS, to correctly execute the pre-commit tasks.

The pre-commit action is currently automated by GitHub actions CI, to verify against pushes and pull-requests.

Testing

The repo includes a test suite built using googletest to verify API functionality. This uses a simple mocked Arduino.h shim to 'simulate' hardware response.

The test suite is automated via a GitHub action. To run the tests locally, you need to install the googletest framework. You'll also need cmake and a c++ compiler on your development machine.

cd .tests/
git clone --depth 1 --branch v1.13.0 https://github.com/google/googletest
cd googletest/
cmake CMakeCache.txt
make
sudo make install
cd ..
source env.sh
make
../src/NullPacketComms

---

I just do this stuff for fun in my spare time, but feel free to:

---

License

The source of this repo uses the MIT open-source license, for details on the current licensing see: LICENSE or click the badge above.