Low-level hardware abstraction layer for
controlling a [Khepera IV robot](https://www.k-team.com/khepera-iv).
> ***Special Thanks*** to the
> [Novel Engineering of Swarm Technology](https://nestlab.net/team) (**NEST**) lab
> at Worcester Polytechnic Institute
> for providing a [reference usage](https://github.com/ilpincy/argos3-kheperaiv)
> of the Khepera IV APIs, and providing us with access to
> their Khepera IV swarms for testing this crate.
## Using this Crate
The documentation for this crate can be
generated by running `cargo doc`; the
generated docs will be written to `release/`.
### ...on any system
Although the _actual_ Khepera libraries
can only be used on an _actual_ Khepera,
this crate exposes a single `HasKhepera4Hardware`
trait which can be compiled on any host.
This trait can be used to create mock
implementations of the Khepera IV system,
which systems can use for integration testing
or simulation when an actual Khepera
is unavailable.
### ...on a real Khepera IV
In addition to adding a dependency
on this crate, you will need to add
(or update) a `.cargo/config.toml` at
the root of your crate containing:
```toml
[target.armv7-unknown-linux-gnueabihf]
linker = "arm-poky-linux-gnueabi-gcc"
rustflags = [
"-C", "link-arg=-march=armv7-a",
"-C", "link-arg=-mfloat-abi=hard",
"-C", "link-arg=-mfpu=neon",
"-C", "link-arg=-mtune=cortex-a8",
"-C", "link-arg=--sysroot=/opt/poky/1.8/sysroots/cortexa8hf-vfp-neon-poky-linux-gnueabi",
]
```
Once this configuration is added, follow
the instructions below on how to cross-compile
this crate (or a crate dependning on it).
## Cross-Compiling from a Linux Host
Before building this crate, or a Crate
_depending_ on this crate, you need to:
1. Install Rust.
2. Install Clang.
3. Install the ARMv7 Rust toolchain: `rustup target add armv7-unknown-linux-gnueabihf`
3. Install [the Khepera IV SDK "light tools"](https://ftp.k-team.com/KheperaIV/software/Gumstix%20COM%20Y/light_tools/poky-glibc-i686-khepera4-image-cortexa8hf-vfp-neon-toolchain-1.8.sh).
Once these tools are installed, you can
build this crate by running:
1. `source /opt/poky/1.8/environment-setup-cortexa8hf-vfp-neon-poky-linux-gnueabi` (assuming your Khepera IV SDK light tools were installed to the default `/opt/poky/1.8` path).
2. `cargo build --release --target=armv7-unknown-linux-gnueabihf`
When the build completes, the release artifacts will be
stored in `target/armv7-unknown-linux-gnueabihf`.
## License and Contributions
Copyright 2023 Alicorn Systems, Inc.
Licensed under the GNU Affero General Public License version 3,
as published by the Free Software Foundation. Refer to
[the license file](LICENSE.txt) for more information.
The files within `vendor/` retain their original copyrights
and licenses, and are included in this repository to simplify
the build process for downstream users.