Skip to content

rgerganov/ggtag

Repository files navigation

Build Status

Overview

ggtag is an e-paper tag that can be programmed with sound using the ggwave library. It is based on the RP2040 microcontroller and has 3.52" e-paper display. Additionally, ggtag supports USB serial programming and allows emulation of 125kHz RFID tags (ASK and FSK).

CrowdSupply

The GGtag's CrowdSupply campaign has started, you can order one here!

Some example tags:

Both firmware and hardware are open source and licensed under the GPLv3 license. The PCB is made by Eurolan, you can find more details about the hardware design in the hardware directory.

Usage

ggtag can be programmed either with sound or with USB serial. To program with sound, you need to put a CR2032 battery in the battery holder and flip the switch to the BATT position. To program with USB serial, you need to connect ggtag to a USB host and flip the switch to the USB position. Both programming modes are supported in the web interface hosted at ggtag.io, all you need is a modern HTML browser.

Programming with sound

Here is a demonstration of how programming with sound works. Initially, three ggtags are listening and then programmed simultaneously using mobile phone. After the initial programming, you need to press the button on the side for ggtag to start listening again. At the end make sure to flip the switch back to USB position in order to preserve the battery.

ggtag-sound.mp4

Programming with USB serial

The web interface is using Web Serial API for USB serial programming, so you need a web browser (e.g. Chrome, Edge) which supports this API. Mobile Chrome running on Android is also supported. Here is a demo of using Pixel5 phone for USB serial programming:

ggtag-usb.mp4

Emulating RFID tags

You can emulate 125kHz RFID tags with ggtag. This is accomplished with an ATtiny85 MCU and the avrfid firmware. When ggtag receives an RFID command, it generates the corresponding avrfid firmware and programs the ATtiny85 with it. Demo with Flipper Zero:

ggtag-rfid-flipper.mp4

Another demo with USB RFID reader:

ggtag-rfid-reader.mp4

Web receiver

There is a web audio receiver which implements the ggtag protocol running at https://ggtag.io/recv/. This could be useful if you want to hack on the protocol and debug stuff directly in the browser.

webrecv-demo.mp4

Python examples

There is a ggtag python package which can be used together with pyserial or ggwave to program the device. See the examples folder for more details.

Known issues

  • If you switch off the battery after successful sound programming, you need to make ~5sec pause before switching it on again.
  • With some RFID readers you need to keep ggtag at 1cm distance for read to be successful.
  • If you want to display non-ASCII text, you need to convert it to image first.

Credits

Project structure

The codebase is structured in the following way:

  • target - contains device only source code
  • shared - contains shared source code between the device and the host library
  • host - contains the host library
  • docs - contains the web interface
  • python - contains Python bindings for the host library
  • examples - contains some examples
  • hardware - contains hardware design files

Component diagram

component diagram

Building the firmware

Follow these steps to build the RP2040 firmware:

git clone https://github.com/raspberrypi/pico-sdk
cd pico-sdk
git submodule init
git submodule update
cd ..
git clone https://github.com/raspberrypi/pico-extras
cd pico-extras
git submodule init
git submodule update
cd ..
export PICO_SDK_PATH=<full_path_to_pico_sdk>
export PICO_EXTRAS_PATH=<full_path_to_pico_extras>
export PICO_TOOLCHAIN_PATH=<full_path_to_arm_toolchain>

git clone git@github.com:rgerganov/ggtag
cd ggtag
git submodule init
git submodule update
mkdir build
cd build
cmake .. -DPICO_BOARD=pico
make

Building the web interface

The host library is compiled to WASM using Emscripten:

source <path_to_emsdk_env.sh>
CXX=emcc make

You can start a local server with make server and access the web interface at http://localhost:8000. There is a hosted version available at https://ggtag.io

Flashing the firmware

Put ggtag into USB mode, press and hold the button and plug the USB cable. Download the latest firmware release and copy the .uf2 file to the RPI-RP2 drive. The tag will reboot and run the new firmware.

Feedback

We'd love to hear your feedback, comments and questions about ggtag in the Project Discussions