vulpes/README.md

# Vulpes
An ESP32-based radio orienteering controller. This repo is for
the code. See below for hardware comments and a link.
[Main project page](https://w1cdn.net/projects/vulpes-radio-orienteering-controller/).

## What
Radio orienteering, or amateur radio direction finding (ARDF) is a 
sport where people run around and look for hidden transmitters. One
necessary component is a controller on each transmitter that tells
it when and what to transmit. 

This is my attempt at a simple, easy-to-use controller with a low 
parts count. Rather than programming a microcontroller and/or 
using DIP switches, delayed starts, and sync cables, the ESP32 development
board lets you set up each controller using a web browser (e.g., on your
smartphone or tablet).

The [ARRL ARDF page](https://www.arrl.org/amateur-radio-direction-finding) 
is an OK starting point for learning about radio orienteering, but 
there are probably better ones. I've never done an RO event before, but have
experience racing and directing adventure races.

## Hardware
I designed a simple custom printed circuit board (PCB) to make
assumbling this controller easy to do. The repo for schematic and
board design is here: [vulpes_hardware](https://amiok.net/gitea/W1CDN/vulpes_hardware).

Because the ESP32 doesn't track time when it is powered off, and
I wanted to avoid delayed starts (e.g., push a button exactly two hours
before an event starts), an additional real-time clock (RTC) is 
included. The RTC runs on a watch battery to track time when the
controller is not powered on.

Morse code is sent according to the parameters set up in the UI. The GPIO
pin triggers a transistor that acts as a switch to close the key connection
on the radio. Code is also shown on the onboard LED of the ESP32 dev board.

## Software/Firmware
Power on the controller by plugging in a micro-USB cable to a 5V 
source (e.g., computer or battery pack). After the device is powered on,
it will start an internal webserver and set up a wireless network called 
"vulpes."

Connect to the "vulpes" wireless network and use a web browser to navigate
to `http://192.168.0.1` (note "http" not "http**s**"). You will see the
settings below. Note that you will not be able to access the Internet while
connected to this network, and each controller sets up a separate network.

**Web UI**
![screenshot of the Vulpes web UI](doc/vulpes_gui.png)

### General Settings
- **Sending Program**
    - Off - nothing is sent
    - Continuous - the message in `Message` is sent to the key GPIO and the
    onboard LED
    - Cycle - the message in `Message` is sent according to the `Cycle Settings`
- **Message**
    - Custom Message - a message defined in `Custom Message`
    - MOE - transmitter 1 message (dit)
    - MOI - transmitter 2 message (dit dit)
    - MOS - transmitter 3 message (dit dit dit)
    - MOH - transmitter 4 message (dit dit dit dit)
    - MO5 - transmitter 5 message (dit dit dit dit dit)
- **Custom Message** - a custom message to be sent when "Custom Message" is selected in `Message`
- **Speed** - speed of Morse code transmission in words per minute (WPM)

### Cycle Settings
These settings only apply when "Cycle" is chosen under `Sending Program`
- **Cycle Start Time** - when to start the next cycle/event (only HH:MM:SS day-of-month matter)
- **Step Length** - how long this transmitter will transmit on each cycle
- **Cycle ID** - what order transmitter is this (1st, 2nd, 3rd, etc.)
- **Number of Transmitters** - how many transmitters there are

### Network Settings
The `Submit and Reboot` button only affects these fields.

#### Network access
- **Access Point** - when using as a wireless access point, the network SSID is "vulpes"
with no password. Connect to wireless network "vulpes" and point your browser to URL http://192.168.0.1 (http, not https)
- **Existing Wireless Network** - connect to the same existing network and use the proper IP address (useful if you have access to the router or a serial connection). If an existing network can't be connected to, an access point will be set up. 

## License
GNU GPLv3. See `LICENSE` file for details, and 
https://choosealicense.com/licenses/ if you're like me and don't
understand all of this stuff.

## Acknowledgments
Special thanks to [Mark Fickett](http://www.markfickett.com/) for his
[arduinomorse](https://github.com/markfickett/arduinomorse) library and 
[N1OIQ](https://sourceforge.net/projects/kb1oiq-ham-radio-projects/files/80m_ardf/) 
for similar design insparation.

## Questions and Contributing
Until I get Gitea set up completely, please email me at w1cdnQRTw1cdn.net, 
but replace "QRT" with @.

I developed the C++ code in Visual Studio Code (VSCode).