This is an open-hardware hand-held scanner, capable of collecting data for HDMapping.

Hardware documementation

Supported hardware

We support the following hardware:

• Raspbery Pi 4 or 5 without any special hardware (bunch of of-the-shelf components and 3D printed parts)
• Raspbery Pi 4 Compute module with custom carrier board. The carrier board is not part of this repository and is available on request.

Both version shares the same software, but are different in hardware (e.g. different GPIO layout, some extra features on custom carrier board). The target hardware is defined during compilation time. If you want to extend this project to different platforms or hardware, please refer to source code available in hardware directory.

3D Model

The source design is available on Onshape, and you can access it here.

The design files for 3D printing are available in the repository's 3mf directory. You can find the file ScannerAssembly.3mf containing the models to be printed.

For optimal results, we recommend printing the assembly with PLA. Don't forget to adjust the 3MF file according to your printer specifications. If you need assistance with this, consider including a brief guide or tips on printer adjustments.

Additionally, we recommend printing a protective cap for Livox Mid-360, which you can find in the LivoxCap.3mf file.

Feel free to reach out if you have any questions or need further assistance!

Bill of Materials

Click here to BIM

Wiring

Wiring manual

Video guide

Time-lapse video guide to build and configure the system.

Youtube video

Note: the video will get outdated eventually, please refer to the manual.

Software

Important notes

Currently, Raspbian Bookworm is recommended for the system. The system is tested on Raspbian Bookworm. The version v0.5 supported Bullseye, the current main branch supports Bookworm. The software can run other distros (e.g. Ubuntu), but it is not tested and maintained.

Update system

sudo apt-get update
sudo apt-get upgrade
sudo apt-get install build-essential cmake git rapidjson-dev debhelper build-essential ntfs-3g libserial-dev libgpiod-dev libzmq3-dev libpistache-dev libcamera-dev linuxptp debhelper libopencv-dev pps-tools ppsh nlohmann-json3-dev

Static IP for eth0

sudo nano /etc/dhcpcd.conf

And add in the end:

interface eth0
static ip_address=192.168.1.5/24
static routers=0.0.0.0    

Systems with network manager [Raspbian Bookwork]

sudo nmcli connection add type ethernet ifname eth0 con-name static-eth0 \
  ipv4.addresses 192.168.1.5/24 \
  ipv4.gateway 0.0.0.0 \
  ipv4.method manual 

verify with :

nmcli device show eth0

eventually you can use

nmtui

Clone and build app

Note that, target hardware is defined during compilation time using -MANDEYE_HARDWARE_HEADER=mandeye-standard-rpi4.h parameter. The MANDEYE_HARDWARE_HEADER is one of the headers in code/hardware_config:

$ ls ./code/hardware_config/mandeye-*.h
./code/hardware_config/mandeye-pro-cm4-bookworm.h
./code/hardware_config/mandeye-pro-cm4-bullseye.h
./code/hardware_config/mandeye-standard-rpi4.h
./code/hardware_config/mandeye-standard-rpi5.h
...

Hardware header	What is supported
mandeye-standard-rpi4.h	Raspberry Pi 4
mandeye-standard-rpi5.h	Raspberry Pi 5
mandeye-pro-cm4-bookworm.h	Raspberry Pi Compute module 4 plus carrier board
mandeye-direct-cm5.h	Raspberry Pi Compute module 5 plus carrier board
mandeye-pro-cm4-bullseye.h	Deprecated

The next example shows how to build the app for Raspberry Pi 4 without a custom carrier board at Raspberry Pi 4.

git clone https://github.com/JanuszBedkowski/mandeye_controller.git
cd mandeye_controller
git submodule init
git submodule update
mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DMANDEYE_HARDWARE_HEADER=mandeye-standard-rpi4.h 
make -j1 # -j4 can be used for 8 Gb version

Test wiring and hardware

Before running the application, you should test the wiring and hardware. You can use the following commands to test the hardware:

cd mandeye_controller/build
./led_demo
./button_demo

Both programs should work correctly, without a need of sudo. If not, check if your user is in gpio group, if not add it:

sudo usermod -a -G gpio $USER

Set USB mount

Follow manual for build and configuration of USB mount https://gist.github.com/michalpelka/82d44a21c29f34ee5320c349f8bbf683

cd /tmp
git clone https://github.com/rbrito/usbmount.git
cd usbmount
dpkg-buildpackage -us -uc -b
cd ..
sudo apt install ./usbmount_0.0.24_all.deb

Edit config sudo nano /etc/usbmount/usbmount.conf: by changing keys:

FILESYSTEMS="vfat ext2 ext3 ext4 hfsplus ntfs fuseblk exfat"
FS_MOUNTOPTIONS="-fstype=vfat,users,rw,umask=000 -fstype=exfat,users,rw,umask=000"
VERBOSE=yes

Install udev rules:

sudo mkdir /etc/systemd/system/systemd-udevd.service.d
sudo nano -w /etc/systemd/system/systemd-udevd.service.d/00-my-custom-mountflags.conf

and add content:

[Service]
PrivateMounts=no

Restart udev:

sudo systemctl daemon-reexec
sudo service systemd-udevd restart

Verify if usb mount works correclty:

touch /media/usb/test

tail -f /var/log/syslog

Installing software on target device

  Then you can build the package:

cd mandeye_controller
mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DMANDEYE_HARDWARE_HEADER=mandeye-standard-rpi4.h
make -j1 # -j4 can be used for 8 Gb version
sudo make install 

Debian package

You can build a DEB package for easier installation on the target device. It can help with deployment on small 1Gb devices.

cd mandeye_controller
mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DMANDEYE_HARDWARE_HEADER=mandeye-standard-rpi4.h
make -j1 # -j4 can be used for 8 Gb version
sudo make package

The package will be available in the build directory.

Choosing Lidar SDK

The software supports different SDKs for the Lidar:

SDK	Variable	Description
Livox SDK	LIVOX_SDK2	Livox SDK version 2 tested with Mid360 and HAP
Ouster SDK	OUSTER	Ouster SDK tested with OS-0-64 (ousteros-image-prod-aries-v2.5.3+20240111055903)
Butter Lidar	BUTTER_LIDAR	Dummy SDK for documentation and testing purposes

Those are shared libraries that are loaded at runtime. You can set the SDK to use in two ways:

1. By setting the MANDEYE_LIDAR_SDK environment variable to LIVOX_SDK2 or OUSTER.
2. By putting the config in location '/media/usb/mandeye_config.json' with the following content:

{
  "lidar_sdk": "LIVOX_SDK2"
}

Installation and usage of the package

To install the package, you need to copy it to the target device and install it with dpkg:

sudo dpkg -i mandeye_controller-0.1.0-Linux.deb

The package will be installed in /opt/mandeye/ directory, the service will be added to /usr/lib/systemd/system/. Note that the service will not start automatically, you need to start it manually or enable it with systemctl. There is a helper script /opt/mandeye/helper.sh that contains some useful commands to start, stop, and restart the service.

If you make any changes post-installation, please run 'sudo systemctl daemon-reload' to reload the service. Note that the changes will be disregarded after reinstallation.

Post installation

Those commands need to be run only once after installation.

Add it to bashrc:

echo "source /opt/mandeye/helpers.sh" >> ~/.bashrc

After that start required services:

mandeye_start

There are optional services that can be started:

Fake PPS

PPS time synchronization generator using GPIO (to other devices)

sudo systemctl enable mandeye_fake_pps.service
mandeye_fakepps_start # PPS generator using GPIO

PTP time synchronization generator using eth0 (works only on Raspberry Pi 5):

sudo systemctl enable mandeye_ptp4l-gm-eth0.service
sudo systemctl enable mandeye_phc2sys-gm-eth0.service 
mandeye_phc2sys_start # PTP clock using eth0
mandeye_ptp4l_grandmaster_start # 

SlavePPS

Slave PPS is a serivce that will adjust system time using PPS signal from master PPS + NMEA.

Disable NTP:

sudo systemctl stop systemd-timesyncd

Start service:

sudo systemctl enable mandeye_slave_pps.service
sudo systemctl start mandeye_slave_pps.service

Libcamera

Cameras:

sudo systemctl enable mandeye_libcamera_cam0.service
sudo systemctl enable mandeye_libcamera_cam1.service
mandeye_cam0_start
mandeye_cam1_start

USB Gnss

Extra USB Gnss:

sudo systemctl enable mandeye_extra_gnss.service 
mandeye_extra_gnss_start

Extra muRata UART IMU (experimental):

sudo systemctl enable mandeye_murata_uart_driver.service
mandeye_murata_uart_imu_start

Services

List state of services:

mandeye_services_status