MeshCore fork · Heltec V4

V4 Presence Companion

This is a MeshCore BLE companion firmware for the Heltec V4. The node also shows on Meshtastic as a presence. You can set the V4's RX amplifier (LNA) from the phone app. A second firmware adds a dual-node mode: press the button five times to change between the companion and a car-node repeater.

Board: Heltec V4 · ESP32-S3 · SX1262 Firmware v1.17.1 + presence Companion build 3744123b Dual-Node build 9f073981
Download the firmware T1000-E Dual-Node

# What this firmware does

This is the standard MeshCore BLE companion for the Heltec V4, with two additions. The node sends a silent Meshtastic presence, and the phone app can set the radio's external RX amplifier.

📱 MeshCore companion BLE

  • The node connects to the MeshCore phone app with BLE.
  • All the normal companion functions operate: contacts, channels, messages, and the map.
  • The V4 screen shows the node status.

🛰️ Meshtastic presence silent

  • The node also shows on Meshtastic. It sends the node name (NodeInfo) and the battery and the run time (Telemetry).
  • It does not send a Meshtastic chat message. It sends a presence only.
  • The location is optional and less accurate (see below). The default is off.

# RX amplifier (LNA) control

The Heltec V4 has an external radio front-end with an RX amplifier (LNA). The repeater firmware sets it with the radio.fem.rxgain command. A companion does not have a serial console — this firmware adds the same setting to the phone app.

📶 Set it in the app

Open the custom-variables list in the MeshCore app. Set radio.fem.rxgain to 1 (on) or 0 (off). The default is on.

💾 The value persists

The value applies to the hardware immediately. The node keeps the value and applies it again at each boot.

The variable shows only on a board with a switchable front-end. The value 1 gives more RX sensitivity and uses more power. Boards with a switchable TX gain also show radio.fem.txgain.

# Meshtastic presence settings

Set the presence from the same custom-variables list. The firmware makes a check of each value and keeps it on the node.

VariableValuesFunction
mt.presence0 / 1Set the presence to on. The default is off.
mt.interval1–1440The time between presence messages, in minutes. The default is 30.
mt.position0 / 1Set the map point to on or off.
mt.precision0, 10–32The location accuracy. 32 is exact. 0 is off.
mt.regionUS, EU_868, and othersThe Meshtastic region and band.
mt.presetLongFast, and othersThe Meshtastic modem preset.
mt.slot0–num. channelsThe Meshtastic frequency slot (1-based). 0 is the default slot.

The node controls the location

🔒 The MeshCore setting controls it

The node sends a location only when MeshCore shares a location. If MeshCore does not share a location, the node sends the node name only. It does not send a map point.

⭕ The location is less accurate

The node makes the location less accurate. The Meshtastic client shows a circle, not a point. The default circle is near 2.9 km. Set mt.precision to change it.

Note: Meshtastic and MeshCore do not use the same radio settings. For each presence, the node sets the radio to Meshtastic, sends the presence, and sets the radio back. This occurs between packets, when the radio is not busy.

# Dual-Node: one firmware, two modes

The Dual-Node firmware is the same idea as the T1000-E Dual-Node, on the Heltec V4. It contains the presence companion above and the car-node repeater. Only one mode operates at a time. To change the mode, press the user button five times.

📱 Companion mode default

  • The full companion above: MeshCore app with BLE, Meshtastic presence, LNA control, screen on.

🚗 Repeater mode Car Node

  • The car-node repeater: the node repeats MeshCore traffic, and it sends its GPS location to Meshtastic when the vehicle stops.
  • Configure it over the air with the carnode and mtbeacon commands, or on the USB serial console.
  • The screen is off in this mode. The screen belongs to the companion mode.
How you see the mode change: after the fifth press the node restarts in the other mode. The screen comes on in companion mode. The screen stays off in repeater mode. The V4 has no buzzer, so there is no beep. Each mode keeps its own settings.

# Download and installation

These firmwares are for the Heltec V4 (OLED) only. For a new board, use a -full.bin file. To update a board that has one of these firmwares, use the smaller .bin file.

Companion only

heltec_v4_companion_radio_ble_mtpresence-3744123b-full.bin new board · 0x01.29 MB heltec_v4_companion_radio_ble_mtpresence-3744123b.bin update · 0x100001.23 MB

Dual-Node (companion + car-node repeater)

heltec_v4_dualmode_carnode_mtpresence-9f073981-full.bin new board · 0x01.80 MB heltec_v4_dualmode_carnode_mtpresence-9f073981.bin update · 0x100001.74 MB SHA256SUMS.txtchecksums

How to install with esptool

  1. Connect the V4 with USB-C. The board shows as a serial port.
  2. For a new board, write the full image to address 0x0 (use the file name that you downloaded):
esptool.py write_flash 0x0 heltec_v4_dualmode_carnode_mtpresence-9f073981-full.bin
  1. To update, write the app image to address 0x10000:
esptool.py write_flash 0x10000 heltec_v4_dualmode_carnode_mtpresence-9f073981.bin
  1. The node starts as a companion. Connect to the node in the MeshCore app with BLE. The screen shows the pairing information.
  2. Open the custom-variables list to set the presence (mt.presence:1) and the LNA (radio.fem.rxgain).
Note: Make a check of a file before you install it. Use the command sha256sum -c SHA256SUMS.txt in the folder with the files. The full image erases the node settings; the update image keeps them.