Heltec V4: Practice. Flashing, Setup, First Messages. Part 2

📌 This is Part 2 of the series. Part 1: Theory explains why this matters.

📦 Unboxing and Preparation

Heltec V4 Contents

⚠️ Important: without antenna connected, the radio module may be damaged. Always attach antenna before powering on.

Heltec V4 Specifications

⚡ Flashing: Web Flasher

Official flasher: https://flasher.meshtastic.org

Requirements

🐧 Linux: Serial Port Permissions

If you see:

[09:52:42.841] Serial: serial_io_handler.cc:157 Failed to open serial port: FILE_ERROR_ACCESS_DENIED

Fix:

# Add user to dialout group
sudo usermod -a -G dialout $USER

# Apply changes (re-login or)
newgrp dialout

# Verify access
ls -l /dev/ttyUSB*  # or /dev/ttyACM*

🔧 Flashing Process

1. Disconnect battery and USB from the board
2. Open web flasher, select:
   • Device: Heltec V4
   • Firmware: 2.7.21 (or latest stable/beta)
   • Variant: Full erase and install
3. Click Erase Flash and Install
4. Hold the PRG button on the board
5. While holding PRG, plug in the USB cable
6. Observe: brief red flash → USB JTAG appears in port dropdown
7. Release PRG, select USB JTAG, click Connect
8. Wait for flashing to complete (terminal shows progress)
9. After Leaving... message, press the RST button (reset)

💡 If flasher doesn’t detect the port - try another cable (not all support data), another USB port, or restart the browser.

🔌 First Connection: Three Ways

After flashing, the board reboots and starts Meshtastic.

Connection Options

⚠️ Bluetooth: only one active connection.
Wi-Fi: multiple devices can connect simultaneously (convenient for stationary nodes).
USB: reliable for setup and debugging, no wireless connection required.

Setup via App (recommended)

1. Install Meshtastic (Android) or the iOS version
2. Launch the app and grant location and Bluetooth permissions
3. Go to the “Devices” tab (router icon) → select the connection type (Bluetooth, Wi-Fi, or Serial), depending on the node’s mode (default is Bluetooth) → tap 🔍 Scan or + Add
4. Confirm pairing

Setup via Wi-Fi

1. The node’s screen will display an IP address (usually 192.168.1.x)
2. Connect to the node’s Wi-Fi network (password shown on screen)
3. Open a browser and go to http://<node_IP_address>
4. The web interface allows viewing data (e.g. JSON messages), but node configuration is not done here. Use one of the following for full setup:
   • Meshtastic mobile app
   • MeshApp
   • Python CLI (meshtastic) over USB, BLE, or Wi-Fi

💡 IP Address: node gets address from your router (not 192.168.4.1!). Exact address displayed on OLED screen.

👤 User Configuration

Core Parameters

💡 ShortName: exactly 4 characters! This appears in message headers. Examples: ponf, KST1, MOW2.

Additional Flags (Optional)

Advanced User Settings

🌐 MQTT Setup for ONEmesh (RU)

ONEmesh - map of Meshtastic devices in Russia. Connecting to their MQTT server lets your node appear on the map and exchange data with other participants.

🔐 What’s transmitted via MQTT: text messages, device metrics (battery, signal), location (if enabled). Data goes to the map and regional Telegram chats per city settings.

Core Parameters

💡 Tip: if “Save” button is inactive - fill settings in stages: basics first (address, login, password), then map, then extra options.

Username Modes

⚠️ Using onemeshd with Downlink enabled can overload local network with internet packets. Use consciously and only with full understanding.

Advanced MQTT Parameters

Common MQTT Issues

📡 LoRa and Channel Settings

LoRa Section

Advanced LoRa Parameters

Channels - Detailed

Configure the Primary channel (index 0):

Secondary Channel (Optional, Index 1)

✅ Important: at least one channel must have PSK: AQ== or be unencrypted for OneMesh server to accept packets.

💡 Secondary channels are created via + in the app. They don’t interfere with main traffic and are useful for private communication.

Channel Management: Tips

• Channel order: Primary must be first (index 0) - system telemetry goes through it.
• Channel names: use Latin, no spaces or special characters.
• PSK lengths: supported: 0 (no encryption), 8, 128, 256 bits. OneMesh requires AQ== (8-bit).
• Export/import: channel settings can be exported to JSON for quick deployment on other nodes.

📍 Position Settings

Fixed Coordinates (for Stationary Nodes)

💡 Coordinates stored as integer × 1e7. In app, enter with 6 decimal places.

Position Packet - Intervals and Precision

Advanced Position Settings

🔐 For privacy: reduce Precision in channel (182 m) and Map precision (729 m), or set fixed coordinates away from real location.

⚙️ Additional Modules

Neighbor Info

🗺️ Map will show layers “Who heard this device” and “Who this device heard” - useful for coverage analysis.

Device - Role and Rebroadcast

Advanced Device Settings

Timezone

Power - for Stability

Display - OLED Optimization

Bluetooth - When WiFi Off

Network - WiFi for Stationary Node

⚠️ With WiFi enabled, Bluetooth auto-disables on ESP32 architecture.

🧩 Module Settings (Continued)

Telemetry

Canned Messages

Disabled Modules (Recommendation for OneMesh)

🔑 Critical Flags and Application Order

1. Channel Name: Primary must be exactly LongFast.
2. PSK: AQ== in primary channel is required for OneMesh filtering.
3. OK to MQTT: On - without this, neighbors can’t relay your packets to server.
4. Save Order (UI bug workaround):
   • LoRa → Region → save
   • Channels → name + PSK + Uplink/Downlink → save
   • MQTT → basic params → save
   • MQTT → Map Reports → save separately
   • Position / Device / Power → save
   • Reboot node
5. Verification:
   • In app: MQTT → status Connected
   • On map: node appears within 1–3 hours
   • In LongFast chat: messages from neighbors visible

🔧 Optimal Flashing Process

For Heltec V4 (Bootloader Workaround)

Due to a Heltec V4 bootloader quirk, the standard order doesn’t always work. Optimal process:

1. Disconnect battery and USB from the board
2. Open web flasher
3. Select device: Heltec V4, firmware: 2.7.21
4. Click Erase Flash and Install
5. Hold the PRG button on the board
6. While holding PRG, plug in the USB cable
7. Observe: brief red flash → USB JTAG appears in port dropdown
8. Release PRG, select USB JTAG, click Connect
9. Wait for flashing to complete
10. After Leaving... message, press the RST button (reset)

💡 Note: this process is described in meshtastic/firmware#8543

📤 First Messages Between Two Nodes

Preparation

1. Flash both boards per instructions above
2. On each, configure:
   • Same region (Russia)
   • Same channel with identical PSK (AQ==)
   • Position enabled: Yes (for testing)
3. Place nodes 10–50 m apart (for initial test)

Test

1. On first node in app: Messages → + → type text → Send
2. On second node: incoming message should appear
3. Check Map tab - if MQTT is enabled, both nodes should appear on map within an hour

Troubleshooting

🆘 Help and Community

• 🗺️ ONEmesh Map - network visualization
• 💬 Telegram Group - questions, help, city coordination
• 📘 Official Meshtastic Docs
• 🐙 Firmware Repository
• 🔧 Heltec V4 Specs