Edgemap is small project built on embedded ARM targets like RaspberryPi4 and Raspberry Pi Zero 2W. It can be cross compiled to various other platforms and integrated to work with AMD64 based PC architectures.
System delivers small browser usable user interface where full world map can be accessed with any End User Device (EUD). Implementation is based on various open source projects like Protomaps, Meshtastic and maplibre-gl-js.
Please note that Edgemap is not complete product as such but offers great integration point to your own developments.
System contains features which might work out of the box for you or require more detailed configuration. Especially networking, SecurePTT and CoT receiving requires quite deep knowledge and planning to be really useful.
Image contains taky a simple COT server for ATAK. CoT server is mainly targeted to read CoT targets in network and illustrate them on Web user interface. This functionality was tested with AN/PRC-169 radios.
CoT implementation to battle space with TLS certificates is painful and dangerous. But as it's running on consumer platforms, there is really no options available, I believe.
Image contains TLS encryption for Web UI connection and offers experimental video conference for 6 team members directly from map user interface. Video conference is based on WebRTC and is implemented with Janus by Meetecho. Please note that TLS is really bad for your OPSEC and I generally would like to use other means to secure connectivity. But with consumer grade EUD's and browsers we are forced to use TLS to make WebRTC working.
QT 5.11.5 is enabled for build and it allows us to do small and simple local user interface to Hyperpixel 4 touch screen. This feature is currently proof of concept placeholder and contains no usable functionality. You could take this further with ease by using QT Creator and configuring it to use toolchain from buildroot environment.
By default this image contains message delivery over Meshtastic LoRA radios. (This can be changed to IP bearer if you need more bandwidth to image transfers for example).
Setup is tested with LILYGO LoRa32 V2.1_1.6 radios and Heltec V3 radios and others should work after configuring correct serial port to "/opt/edgemap/meshpipe/meshtastic.env"
Meshtastic implementation is still highly experimental and contains only message delivery over meshtastic radios. Following picture gives overview how FIFO pipes are used to deliver payload to/from radios.
You can deliver MIL symbols as sensor markers between Edgemap nodes with 'sensorMarker' message.
Copy paste following messages to message dialog on Edgemap UI and expect them to appear to other nodes map after delivery is done via Meshtastic radios.
sensorMarker|[58.9074826,23.5766601]|path13,GSM Network,30046000001302000000
sensorMarker|[58.3830883,27.3655486]|path14,Water pump control override,30066000001504000000
sensorMarker|[58.3102102,27.3957824]|path15,Cloud outages,30066000001608000000
sensorMarker|[58.2887415,27.6258087]|path17,GNSS L2,30065200001102000001
sensorMarker|[58.2887415,27.6258087]|path18,GNSS L2+L1,30065200001102000001
sensorMarker|[58.0967511,27.5097656]|path19,Hand over delays,30055200000000000000
sensorMarker|[58.1616254,27.1953678]|path20,Core router #12,30046000001402000000
sensorMarker|[58.2340188,27.4486541]|path21,Power outage,30046000001606000000
sensorMarker|[58.3786785,26.7249298]|path22,OT + Sensory team,30031000001505010000
sensorMarker|[58.2320306,27.3464727]|path23,Cellular Jamming,30011000001505040000Z
sensorMarker|[58.0549952,27.0552062]|path24,Starlink uplink detected 04:19,30015000001101000000
To save bandwidth on Meshtastic communication, some of messaging channel functions have been commented out on UI code. We don't deliver 'drag marker' or 'geolocation' over Meshtastic and we have increased presence indication sending interval to 2 minute.
Edgemap contains simple example which shows you how to use Meshtastic node as detection sensor. Example is done with RAK wireless Wisblock Meshtastic Starter Kit and you can use closing switch between J12: PIN1 (VDD) and J11: PIN2 (IO2).
First you need to configure your Sensor unit. Note that 'detection_sensor.name' must contain given format and only ID ('12') can be changed by user, based on your sensor numbering.
meshtastic --port /dev/ttyACM0 --set detection_sensor.name "12|sensor|||"
meshtastic --port /dev/ttyACM0 --set detection_sensor.monitor_pin 34
meshtastic --port /dev/ttyACM0 --set detection_sensor.state_broadcast_secs 300
meshtastic --port /dev/ttyACM0 --set detection_sensor.minimum_broadcast_secs 5
meshtastic --port /dev/ttyACM0 --set detection_sensor.detection_triggered_high true
meshtastic --port /dev/ttyACM0 --set detection_sensor.enabled true
Configuring sensor to Edgemap is simple. You send one alarm event and Edgemap will show 'unknown sensor' indication, where you can pick location on map and give description. All further alarms are then shown on map.
Note that this implementation is still work in progress.
You can also update highrate target information to map via websocket connection. See readme in highrate/ directory.
Experimental support for reticulum network is included on build. Currently we have to disable meshtastic when reticulum is activated into use, but this might change in future. For reticulum there is "Reticulum MeshChat" included, which is independent browser usable chat and nomad network access tool.
For reticulum message delivery image contains LXMF based messaging and reticulum links based option. Both of these are currently under development and field testing.
SecurePTT branch contains possbility to use small scale demo of full duplex Push-To-Talk (PTT) with exclusive level of security, where PTT streams are encrypted with One-Time-Pad (OTP). This functionality can be configured to following modes, depending on use case:
- Global unicast SecurePTT coverage via routing gateway servers
- Global multicast SecurePTT coverage via routing gateway servers
- Local MESH/MANET network segments
SecurePTT offers flexibility to cipher your PTT streams and by default we use three layers to transport UDP packets between nodes.
Outermost level (A) can be selected to hide meta-data of layer (B) which encapsulates (C), One-Time-Pad encrypted stream between nodes.
Depending what audio hardware you choose to use, wiring of PTT button varies. You could use USB attached headset and utilize GPIO pin to act like a PTT button:
For Codec Zero with Kenwood SMC-34 wiring looks like this:
You can modify SecurePTT code to support Symmetric algorithms (if you find a math you can trust). Implementation supports also securing plain text UDP streams of your existing MESH/MANET gears like AN/PRC-169 making your PTT comms resistant to UDP jamming and interception.
Note that this repository does not contain keying environment and you need separately configure your network setup and nodes to support SecurePTT.
For operations security we can use optional Linux Unified Key Setup (LUKS) to encrypt data partition on same MicroSD card (or external USB drive). Since we aim to use RPi4 in headless configuration we use systemd-cryptsetup with FIDO2 key. With this approach we can start unit to fully operational state with FIDO2 key plugged in to USB port and after unit is booted (and LUKS partitions are opened) - we can remove FIDO2 key.
Note that this branch is configured to use third partition for maps, elevation model and imagery without encryption.
This version does NOT have high rate target, simulations, CoT reading and AN/PRC-169 support.
If you choose to use browser based geolocation, configure installation to use TLS connection.
To build edgemap firmware, you need to install Buildroot environment and clone this repository as 'external tree' to buildroot. Make sure you check buildroot manual for required packages for your host, before building.
Clone repositories
mkdir ~/build-directory
cd ~/build-directory/
git clone https://github.com/resiliencetheatre/rpi4edgemap.git
git clone https://git.buildroot.net/buildroot
cd buildroot/
# We checkout verified version on master branch
git checkout 66f66bbdb50a65ed27660bbe4f9c1598f94b0c42
You can use latest master or checkout version 66f66bbdb50a65ed27660bbe4f9c1598f94b0c42 as above,
which I've tested (Nov 14th, 2024). Please note that buildroot version, kernel and other system
components needs to be in 'sync' and this is an art in embedded design.
Modify buildroot standard rpi-firmware package file and change
firmware version tag to match kernel version (6.11.7) we're using.
# package/rpi-firmware/rpi-firmware.mk
RPI_FIRMWARE_VERSION = 5476720d52cf579dc1627715262b30ba1242525e
Disable hash check by deleting rpi-firmware.hash file:
cd ~/build-directory/buildroot
rm package/rpi-firmware/rpi-firmware.hash
Protobufs 28.1
This version uses protobufs 28.1 (for python-meshtastic) which is not yet in buildroot master branch and you need to patch your buildroot manually before building the image.
cd ~/build-directory/buildroot
patch --directory=. --strip=1 < ../rpi4edgemap/buildroot-extras/v5-2-4-package-python--protobuf-bump-to-version-28.1.diff
Export BR2_EXTERNAL variable, make defconfig and start build with make:
export BR2_EXTERNAL=~/build-directory/rpi4edgemap
cd ~/build-directory/buildroot
make rpi4_edgemap_6.11_defconfig
make
After build is completed, you find image file for MicroSD card at:
~/build-directory/buildroot/output/images/sdcard.img
Use 'dd' to copy this image to your MicroSD card.
First boot requires you to create maps partition, set hostname and create CA certificate. You can login with 'root' and 'edgemap' as password to your Edgemap instance.
First create partition for maps:
create-partition-noenc.sh
Create CA and set hostname:
# /opt/edgemap/ca/tls-setup.sh
Usage: tls-setup.sh [CA-NAME] [DNS-NAME]
# Example:
/opt/edgemap/ca/tls-setup.sh edgeCA edgemapx
# Reboot after this completes:
reboot
This will set your unit hostname and create wifi access point with same name. Wifi AP psk is 'abc12345', feel free to change it.
You can copy planet.pmtiles to your map partition with computer or try to download it directly from Edgemap:
cd /opt/data
wget --no-check-certificate https://build.protomaps.com/20240520.pmtiles -O planet.pmtiles
Check latest pmtiles here or generate it yourself.
Link downloaded planet.pmtiles under /opt/edgemap/edgeui
cd /opt/edgemap/edgeui/
ln -s /opt/data/planet.pmtiles .
You can optionally patch iqaudio-codec.c driver to remove really anoying delay on audio opening. Download this patch and place it under buildroot/linux/ before build.
If you wish to have codec2 binaries on your edgemap device, use provided buildroot-extras/libcodec2.mk file
and copy it over to buildroot provided one:
# libcodec2 (optional)
rm ~/build-directory/buildroot/package/libcodec2/libcodec2.hash
cd ~/build-directory/rpi4edgemap/buildroot-extras/
cp libcodec2.mk ~/build-directory/buildroot/package/libcodec2/libcodec2.hash
On first boot on your RPi 4, you must create maps partition and create CA + certificates.
To create maps partition, run create-partition-noenc.sh script on RPi4. Then you need to
place pmtiles to your MicroSD second partition and link them under /opt/edgemap/edgeui/
on running instance.
You need to have full planet OSM pmtiles and A global terrain RGB dataset from Mapzen Joerd project.
As full planet pmtiles file is HUGE (>100 GB) you can either copy it manually to card or use inbuilt wget to download it.
Preparing card 'maps' partition after first boot, you could enter following command:
# create-partition-noenc.sh
This will create third partition with EXT4 filesystem and label 'maps'. After create completes, reboot your RPi4 to automount partition on next boot.
After boot completes with and created 'maps' partition is usable, you can download pmtiles to card with:
# cd /opt/data
# wget --no-check-certificate https://build.protomaps.com/20240520.pmtiles -O planet.pmtiles
# sync
Note that downloading over 100 GB file might take several hours to complete, depending your connection speed.
Configure USB serial port of your meshtastic radios:
# /opt/edgemap/meshpipe/meshtastic.env
MESHTASTIC_PORT="/dev/ttyACM0"
- LilyGo: /dev/ttyUSB0
- Heltec: /dev/ttyACM0
You can find reticulum (rnsd) configuration file at:
/opt/meshchat/config
This branch has gpsd package which can read your locally attached GPS receiver(s) and expose location information to localhost socket. There is also gpsreader as buildroot package and it's used to read gpsd socket and output location string to fifo file. This fifo is delivered to map UI via websocket.
Locally connected GPS is good companion for Edgemap with Meshtastic radios. Typically browser based geolocation (also present in edgemap UI) requires TLS connection between EUD (client) and edgemap (server). Since TLS connection requires complex and meta data enriched certificates to be present and real time (difficult to obtain in battle space) we offer edgemap UI without TLS to local network connected EUD's. Browser geolocation requires also Cell, Wifi and BT to be active (stupidity in battle space) for optimum results.
You can configure GPS serial port:
# /etc/default/gpsd
DEVICES="/dev/ttyUSB1"
Daemon (gpsd) and 'gpsreader' is started automatically after you plug GPS in USB port.