Source: hardware/BUILD.md

HerdTag v1: hardware build plan

Batch: 10 working tags plus 2 spares (buy for 12), and 1 gateway. Band: US915. Builder: comfortable with soldering and firmware. Makerspace: FDM printer, SLA printer, soldering stations.

Every price below is an estimate from listings checked on 2026-11-07. Prices move, and RAK's own store doesn't always include US tariffs. Anything marked VERIFY couldn't be confirmed online and needs checking before you order or build.

1. Architecture

Each tag is an off-the-shelf RAKwireless WisBlock stack:

• RAK4631 core: an nRF52840 MCU and an SX1262 LoRa radio.
• RAK19007 base board: battery charger plus solar input.
• RAK12500 GNSS module in slot A.
• RAK1904 accelerometer in slot C.
• A small hand-soldered cue board driving a sealed piezo and, optionally, a coin vibration motor.

The fence logic runs on the tag (firmware/, a C port of src/herdtag/controller.py). The tag sends 11-byte position reports over LoRaWAN to one farm gateway, which forwards them to The Things Stack and then by webhook to our backend. Fences come back down as fragmented downlinks.

                 ┌──────────────── tag (in sealed case, bolted to ear-tag panel) ────────────────┐
 GNSS patch ─────┤ RAK12500 (slot A, I2C)      RAK1904 LIS3DH (slot C, INT1→WB_IO3)            │
 antenna         │          \                    /                                              │
 915 MHz FPC ────┤  RAK4631 core (nRF52840 + SX1262)  ── WB_A1 ─▶ MOSFET ─▶ piezo (cue)         │
 (+ BLE FPC)     │          │                         ── WB_IO1 ─▶ MOSFET ─▶ coin motor (opt.)   │
                 │  RAK19007 base: charger ◀── LiPo (JST PH 2.0) ◀── solar 5 V (JST ZH 1.5)      │
                 └───────────────────────────────────────────────┬───────────────────────────────┘
                                                                  │ LoRaWAN US915 FSB2, 11 B FPort 1 ↑ / fence frags FPort 2 ↓
                                         RAK7268V2 gateway (Ethernet/Wi-Fi backhaul)
                                                                  │
                             The Things Stack Sandbox (nam1) ── webhook ──▶ backend POST /ingest/ttn

2. Platform check: what I verified

Substitution decision:

• Buy the RAK12500 while stock exists. It's lower power, and it uses the u-blox protocol, which carries straight into a v2 on the MAX-M10S.
• If it's sold out, use the RAK12501. That means slot A and UART, and the firmware GNSS driver changes from u-blox UBX to NMEA/CASIC.

3. Firmware pin map (for firmware/tag/pins.h)

Firmware conflict: the current placeholders in firmware/tag/pins.h (PIN_CUE WB_IO3, PIN_VIBE WB_IO4) need changing. WB_IO3 is the accelerometer interrupt in slot C, and WB_IO4 isn't broken out on the RAK19007 headers. Use the values above.

4. Cue driver ("cue board"): one per tag, on a 20 × 30 mm perfboard

 VBAT (3.7 V from J11 pin 4)
   │                         │
   ├──────────┐              ├───────────┬─────────┐
   │          │              │           │         │
 [PIEZO]   [R3 1k]        [MOTOR]     [D1 ▲]    [C2 100n]
   │  AT-1442 │           10 mm coin  1N4148W    (across motor)
   │          │              │      (cathode→VBAT)  │
   ├──────────┘              ├───────────┴─────────┘
   │ D                       │ D
  Q1 AO3400A               Q2 AO3400A           Q = N-MOSFET, SOT-23 (logic-level, Vgs(th) ≤ 1.45 V)
   │ S                       │ S
  GND                       GND

 PIN_CUE (WB_A1) ──[R1 100Ω]──┬── G(Q1)        PIN_VIBE (WB_IO1) ──[R4 100Ω]──┬── G(Q2)
                              [R2 100k]                                       [R5 100k]
                               │                                               │
                              GND                                             GND
 Decoupling: C1 10 µF + 100 nF from VBAT to GND at the board's VBAT entry.

• Piezo: use a PUI AT-1442-TT-WP-R, externally driven, IP67, resonant at 4.25 kHz, 84 dB at 10 V and 10 cm (DigiKey).
• Drive it with a ~4.25 kHz, 50% square wave on PIN_CUE.
• At 3.7 V it will be noticeably quieter than its 84 dB rating. That's a built-in loudness cap.
• R3 bleeds the piezo's charge so the MOSFET can switch it.
• Coin motor: a 3 V, 10 mm coin vibration motor. Drive it with on/off pulses (or ≤ 1 kHz PWM if you need lower strength). D1 is the flyback diode.
• Wiring: 30 AWG silicone wire from header J11. Pin order on J11 is AIN1 / IO1 / IO2 / VBAT; GND comes from J12. VERIFY pin 1 orientation on the silkscreen.

5. Bill of materials (buy for 12 tags)

5a. Per-tag electronics

5b. Cue actuators and cue board

5c. Power

5d. Gateway

5e. Tools and consumables (skip what the makerspace already has)

5f. Mounting

Grand total (estimate)

The cost of goods per tag is about $95. That's prototype pricing on dev modules; the v2 target is under $50 BOM.

6. Makerspace sessions

Session 1: bring up ONE tag (about 4 h)

Tools: soldering station, multimeter, PPK2, laptop with Arduino IDE / PlatformIO + RAK nRF52 BSP, calipers.

• [ ] Antennas on BEFORE first power. LoRa on the IPEX marked LoRa, BLE on BLE, GNSS patch on the RAK12500. Never let the SX1262 transmit without an antenna; it can damage the PA.
• [ ] Seat the RAK4631 on the CPU slot, the RAK12500 on slot A, and the RAK1904 on slot C. Use the M1.2 screws.
• [ ] Check the LiPo polarity against the RAK19007 silkscreen with a meter. If it's reversed, re-pin it. Don't trust the wire colors.
• [ ] Flash a blink, then an I2C scan. You should see 0x42 (GNSS) and 0x18/0x19 (accel).
• [ ] Build the cue board. Run the piezo at 4.25 kHz and measure the dB at 10 cm. Test the motor.
• [ ] Flash the firmware/ tag build (see the firmware README) with keys from TTS (section 7).
• [ ] GNSS outdoors with open sky. A cold start can take a minute or more. Indoors it may never fix.
• [ ] OTAA join on US915 FSB2 and confirm the 11-byte uplink reaches the backend.
• [ ] PPK2 (source-meter mode at 3.7 V into the battery connector): record sleep current, one GNSS fix (energy and duration), and one uplink (energy). Put the numbers into src/herdtag/power.py.

Pass when:

• Join succeeds.
• The uplink decodes correctly.
• The hot fix takes 5 s or less.
• Sleep current is 50 µA or less (target is closer to 20 µA). If it's higher, find the leak before building 11 more.
• The battery ADC reads within 50 mV of the multimeter.

Pitfalls:

• A device on the wrong sub-band never joins. That means FSB2 has to be set in both the firmware and the gateway.
• The base board charger reads USB-attached voltage, not the battery's.
• Some cheap LiPos lack a PCM. Don't use those.

Session 2: build the other 11 (about 5–6 h)

• [ ] Assembly line: 11 cue boards first, then the stacks, then the antennas, then polarity checks, then flashing.
• [ ] Label each tag with a number that matches its TTS device ID (herdtag-01 … herdtag-12).
• [ ] Run the Session 1 checks on each one: I2C scan, cue, join, uplink, a 10-minute sleep-current check.
• [ ] Conformal-coat the cue boards. Mask the connectors.

Pass when 12 out of 12 join and uplink. Any board failing the sleep current check gets set aside as a spare or for debugging.

Session 3: enclosures, sealing, abuse tests (about 4 h plus printing beforehand)

• [ ] Measure the real stack height, piezo, and battery. Edit enclosure/tag_case.scad and print one base and lid in PETG to fit-check.
• [ ] Fit-check, adjust, then print 12 sets in SLA tough resin for anything going on an animal. PETG is fine for walk tests.
• [ ] Set the heat-set inserts. Fit the O-ring cord with grease. Seal the piezo with RTV. Add a silica gel packet.
• [ ] Soak test: a case with tissue paper inside, 30 min at 30 cm depth. Pass if the tissue is dry.
• [ ] Drop test: 1.5 m onto concrete, 6 faces. Pass if it's still working and still sealed.
• [ ] Cold test: freezer overnight at about -15 °C, then a join plus a fix. Note that LiPos must not charge below 0 °C. Flag this for the firmware and the winter field plan.
• [ ] Weigh the complete tag, including the ear-tag panel. Target is under 60 g.

Session 4: walk tests, no cattle (half a day, outdoors at the farm or a park)

• [ ] Mount the gateway as high as possible. Draw a test pasture in the backend and push it to the tags.
• [ ] Static accuracy: 3 tags on a fence post for 30 min. Compute the p50/p95 error and compare it to the sim's 2.5 / 5.3 m assumption.
• [ ] Coverage: walk the farm boundary with 2 tags and log uplink delivery %. Pass at 95% or better.
• [ ] Cue timing: a person walks at grazing pace and at walking pace toward the fence. The cue should fire in the warning zone, and stop on a turn or when the person backs away.
• [ ] Log everything and fit GpsModel in src/herdtag/sim.py to the real error data.

7. The Things Stack Sandbox + gateway setup

1. Create an account on The Things Stack Sandbox, cluster nam1 (nam1.cloud.thethings.network).
2. Gateway: Console → Gateways → Register. Enter the EUI from the RAK7268V2's web UI. Set the frequency plan to "United States 902–928 MHz, FSB 2 (used by TTN)".
3. On the gateway's WisGate OS: LoRa → work mode Packet Forwarder → Basic Station (or Semtech UDP) → server nam1.cloud.thethings.network. Set region US915 and sub-band 2 (channels 8–15, plus 65 for 500 kHz).
4. Application: create herdtag. Register end devices manually: LoRaWAN 1.0.3, regional parameters RP001 1.0.3 rev A, same FSB2 plan, OTAA, JoinEUI 0000000000000000, DevEUI and AppKey generated. Bulk-register 12 with the CLI: bash ttn-lw-cli login for i in $(seq -w 1 12); do ttn-lw-cli end-devices create herdtag herdtag-$i \ --dev-eui $(openssl rand -hex 8) --join-eui 0000000000000000 \ --frequency-plan-id US_902_928_FSB_2 --lorawan-version 1.0.3 \ --lorawan-phy-version 1.0.3-a --with-root-keys done ttn-lw-cli end-devices list herdtag # copy DevEUI/AppKey into each tag's firmware
5. Uplink webhook: Application → Integrations → Webhooks → Custom webhook. - Format: JSON. - Base URL: https://<backend-host>. - Enable Uplink message with path /ingest/ttn. - The backend reads the standard TTS v3 uplink JSON (uplink_message.frm_payload, base64, 11 bytes on FPort 1). - No payload formatter is needed; the backend decodes the bytes itself. - Add a shared-secret header, and have the backend check it.
6. Fence downlinks: create an API key with "write downlink" rights. - The backend queues fragments on FPort 2 through POST /api/v3/as/applications/herdtag/webhooks/<id>/devices/<dev>/down/push. - Tags are Class A, so a downlink only arrives right after an uplink, one fragment per uplink. - The firmware should send a short follow-up uplink while the network reports more downlinks pending (the frame-pending bit), so a fence doesn't take hours to arrive. - 51-byte fragments fit the US915 RX1/RX2 data rates.

8. First cattle fitting: safety and welfare (Phase 2, not before Sessions 1–4 pass)

• A vet or experienced handler applies the tag, in the middle third of the ear between the cartilage ribs. Keep clear of the official ID tag. Don't remove or replace official ID.
• Weight under 60 g on the animal. Inspect the ears daily for 14 days, then twice a week. Remove the tag at any sign of infection or tearing.
• Sound cap: set a maximum SPL at 10 cm with the vet and behavior specialist, measured with the meter. Start low. The firmware caps bursts per episode and per hour; never escalate by volume.
• Only inside an existing physical fence, with no roads or hazards reachable. A handler is present for the first sessions.
• No electrical stimulus in v1. This hardware has none.
• Pre-register the trial thresholds (see PLAN.md Phase 2) before the first animal is tagged.

9. Path to v2 (after Phase 2 data)

• Custom 4-layer PCB: nRF52840 or nRF54L + SX1262 (or a combined module like RAK3172/STM32WL), u-blox MAX-M10S (25 mW tracking), LIS2DW12 accelerometer, an on-board piezo driver, and a solar MPPT/charger IC (e.g. BQ25570-class).
• Chip antennas, and a 300–500 mAh pouch cell shaped to the tag.
• Target ≤ 40 g, about 7 × 4 × 2.5 cm (Cornell V2 scale), in injection-moulded nylon. That gets the BOM under $50 at volume.
• Redesign the cue around whatever stimulus the Phase 2 data says works. That includes a two-tag, left/right option for herding.