Skip to content

Commit 1ae819e

Browse files
ponfertatoponfertato
committed
🚧site update
1 parent 4961991 commit 1ae819e

2 files changed

Lines changed: 664 additions & 0 deletions

File tree

‎content/blog/mesh/heltec-v4-practice.en.md‎

Lines changed: 332 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,332 @@
1+
---
2+
author: ["Potato Energy Team", "ponfertato"]
3+
categories: ["hardware", "mesh", "lora", "tutorial"]
4+
date: "2026-04-27T10:30:00+03:00"
5+
description: "Heltec V4: unboxing, flashing, MQTT setup for ONEmesh, first messages between nodes. Part 2: Practice."
6+
draft: false
7+
series: ["Mesh Networks"]
8+
slug: "practice"
9+
tags:
10+
["Heltec", "esp32", "meshtastic", "firmware", "mqtt", "onemesh", "tutorial"]
11+
title: "Heltec V4: Practice. Flashing, Setup, First Messages. Part 2"
12+
---
13+
14+
> 📌 **This is Part 2 of the series**. [Part 1: Theory]({{< ref "/blog/mesh/heltec-v4-mesh-intro.en.md" >}}) explains why this matters.
15+
16+
---
17+
18+
## 📦 Unboxing and Preparation
19+
20+
### Heltec V4 Contents
21+
22+
| Component | Purpose |
23+
| --------------- | --------------------------------------- |
24+
| Board ~60×30 mm | ESP32-S3R2 + SX1262, OLED 128×64, USB-C |
25+
| Antenna (IPEX) | Connect to `ANT` port - **mandatory!** |
26+
| USB-C cable | Power + flashing + debugging |
27+
| Pins (optional) | For external sensors/antennas |
28+
29+
> ⚠️ **Important**: without antenna connected, the radio module may be damaged. Always attach antenna before powering on.
30+
31+
### Heltec V4 Specifications
32+
33+
| Component | Description |
34+
| -------------------- | ---------------------------------------------------------- |
35+
| **MCU** | ESP32-S3R2 (WiFi + Bluetooth) |
36+
| **LoRa Transceiver** | Semtech SX1262 |
37+
| **Frequencies** | 863–870 MHz (EU), 902–928 MHz (US) |
38+
| **Display** | 0.96" OLED 128×64 |
39+
| **Power** | Up to +28±1 dBm (High Power option) |
40+
| **Power Supply** | USB-C + optimized LiPo management |
41+
| **Connectors** | USB-C, U.FL/IPEX for LoRa, 1.25-8Pin GNSS, 1.25-2Pin Solar |
42+
| **Form Factor** | Pin-compatible with V3/V3.1 |
43+
44+
---
45+
46+
## ⚡ Flashing: Web Flasher
47+
48+
Official flasher: [https://flasher.meshtastic.org](https://flasher.meshtastic.org)
49+
50+
### Requirements
51+
52+
| Requirement | Why |
53+
| ------------------------------------------------ | ------------------------------------------ |
54+
| **Chromium-based browser** (Chrome, Edge, Brave) | Web Serial API works only there |
55+
| **Serial port access** | On Linux - user must be in `dialout` group |
56+
| **Battery disconnected** | During flashing - USB power only |
57+
58+
### 🐧 Linux: Serial Port Permissions
59+
60+
If you see:
61+
62+
```
63+
[09:52:42.841] Serial: serial_io_handler.cc:157 Failed to open serial port: FILE_ERROR_ACCESS_DENIED
64+
```
65+
66+
**Fix**:
67+
68+
```bash
69+
# Add user to dialout group
70+
sudo usermod -a -G dialout $USER
71+
72+
# Apply changes (re-login or)
73+
newgrp dialout
74+
75+
# Verify access
76+
ls -l /dev/ttyUSB* # or /dev/ttyACM*
77+
```
78+
79+
### 🔧 Flashing Process
80+
81+
1. **Disconnect** battery and USB from the board
82+
2. Open [web flasher](https://flasher.meshtastic.org), select:
83+
- Device: `Heltec V4`
84+
- Firmware: `2.7.15` (or latest stable)
85+
- Variant: `Full erase and install`
86+
3. Click **Erase Flash and Install**
87+
4. **Hold the `PRG` button** on the board
88+
5. **While holding `PRG`**, plug in the USB cable
89+
6. Observe: brief red flash → `USB JTAG` appears in port dropdown
90+
7. Release `PRG`, select `USB JTAG`, click **Connect**
91+
8. Wait for flashing to complete (terminal shows progress)
92+
9. After `Leaving...` message, **press the `RST` button** (reset)
93+
94+
> 💡 If flasher doesn't detect the port - try another cable (not all support data), another USB port, or restart the browser.
95+
96+
---
97+
98+
## 🔌 First Connection: Three Ways
99+
100+
After flashing, the board reboots and starts Meshtastic.
101+
102+
### Connection Options
103+
104+
| Interface | How to Connect | When to Use |
105+
| ------------- | -------------------------------------------------------------- | ------------------------------------------------ |
106+
| **Bluetooth** | Meshtastic app (Android/iOS) → scan devices | Portable node, one active connection |
107+
| **Wi-Fi** | Node creates AP → connect to your network → IP shown on screen | Stationary node, multiple devices simultaneously |
108+
| **USB/COM** | Connect via terminal (PuTTY, screen) | Home node, debugging, direct access |
109+
110+
> ⚠️ **Bluetooth**: only one active connection.
111+
> **Wi-Fi**: multiple devices can connect simultaneously (convenient for stationary nodes).
112+
> **USB**: reliable for setup and debugging, no wireless connection required.
113+
114+
### Setup via App (Recommended)
115+
116+
1. Install [Meshtastic](https://meshtastic.org/docs/software/android/installation/) (Android) or [iOS version](https://apps.apple.com/app/meshtastic/id1686803353)
117+
2. Launch, grant location and Bluetooth permissions
118+
3. Tap `+` → select your node (by name `Meshtastic_XXXX`)
119+
4. Confirm pairing
120+
121+
### Setup via Wi-Fi
122+
123+
1. Node screen displays IP address (usually `192.168.1.x`)
124+
2. Connect to node's Wi-Fi network (password shown on screen)
125+
3. Open `http://<node_ip>` in browser
126+
4. Configure via web interface
127+
128+
> 💡 **IP Address**: node gets address from your router (not `192.168.4.1`!). Exact address displayed on OLED screen.
129+
130+
---
131+
132+
## 👤 User Configuration
133+
134+
### Core Parameters
135+
136+
| Parameter | Value | Note |
137+
| -------------- | ------------------------- | ------------------------------------------ |
138+
| **Long Name** | `[PE] ponfertato` | Full name (up to 20 characters) |
139+
| **Short Name** | `ponf` | Short name (**maximum 4 characters**) |
140+
| **Role** | `CLIENT` or `CLIENT_MUTE` | For cities with >200 nodes - `CLIENT_MUTE` |
141+
142+
> 💡 **ShortName**: strictly 4 characters! This is the identifier in messages.
143+
144+
---
145+
146+
## 🌐 MQTT Setup for ONEmesh (RU)
147+
148+
[ONEmesh](https://map.onemesh.ru) - map of Meshtastic devices in Russia. Connecting to their MQTT server lets your node appear on the map and exchange data with other participants.
149+
150+
> 🔐 **MQTT transmits**: messages, device metrics, location (if enabled) to the map and Telegram chats according to region/city settings.
151+
152+
### Core Parameters
153+
154+
| Parameter | Value | Note |
155+
| ----------------------- | -------------------------------- | ------------------------------------------------------------ |
156+
| **MQTT Address** | `mqtt.onemesh.ru` | Community server |
157+
| **Username** | `onemesh` | Default; `onemeshz` / `onemeshd` - for downlink |
158+
| **Password** | `onecat` | Shared for all |
159+
| **Encryption enabled** | `Yes` | If channels have PSK |
160+
| **JSON enabled** | `No` | Not needed for map |
161+
| **TLS enabled** | `Yes` | If not working - try `No` |
162+
| **Root topic** | `msh/RU/XXX` | `XXX` = city code ([list](https://map.onemesh.ru/mqtt.html)) |
163+
| **Proxy to client** | `Yes` (Bluetooth) / `No` (Wi-Fi) | Depends on connection method |
164+
| **Map reports** | `Yes` | Send position to map |
165+
| **I agree** | `Yes` | Accept terms |
166+
| **Precision** | `729 m` | Coordinate precision on map |
167+
| **Map report interval** | `3600 s` (1 hour) | Minimum interval |
168+
169+
> 💡 **Tip**: if "Save" button is inactive - fill settings in stages: first basics (address, login, password), then map, then extra options.
170+
171+
### Username Modes
172+
173+
| Username | Downlink | When to Use |
174+
| ---------- | ----------- | ----------------------------------------------------------------------------------------- |
175+
| `onemesh` | ❌ Disabled | Most users - safe mode |
176+
| `onemeshz` | ✅ Zero-hop | If you need internet data but won't rebroadcast over radio |
177+
| `onemeshd` | ✅ Full | Only for integrations, connecting network segments; **not recommended** for regular nodes |
178+
179+
> ⚠️ Using `onemeshd` with Downlink enabled adds load to the radio network. Use consciously.
180+
181+
---
182+
183+
## 📡 LoRa and Channel Settings
184+
185+
### LoRa Section
186+
187+
| Parameter | Value | Why |
188+
| --------------- | -------- | ----------------------------------------------- |
189+
| **Region** | `Russia` | Auto-sets 433 MHz frequency and MQTT root topic |
190+
| **Hop limit** | `5` | Max message hops; increase for large networks |
191+
| **Ignore MQTT** | `No` | Accept packets that came via internet |
192+
| **OK to MQTT** | `Yes` | Allow neighbors to forward your data to map |
193+
194+
> 🔁 If you change region - verify `Root topic` in MQTT updated automatically.
195+
196+
### Channels
197+
198+
Configure the **Primary channel**:
199+
200+
| Parameter | Value | Note |
201+
| -------------------- | ------- | --------------------------------------------------------------- |
202+
| **PSK** | `AQ==` | Base encryption key; required if MQTT encryption is on |
203+
| **Uplink enabled** | `Yes` | Send data from this channel to MQTT |
204+
| **Downlink enabled** | `No` | Receive data from MQTT (enable only with `onemeshz`/`onemeshd`) |
205+
| **Position enabled** | `Yes` | Transmit coordinates via this channel |
206+
| **Precise location** | `No` | Hide exact coordinates from other nodes |
207+
| **Precision** | `182 m` | Position precision in channel |
208+
209+
> ✅ Setting one channel with `PSK`, `Position enabled`, and `Precision` is enough - even without MQTT, a neighboring node can forward your data.
210+
211+
---
212+
213+
## 📍 Position Settings
214+
215+
### GPS Device
216+
217+
| Parameter | Value | Recommendation |
218+
| ------------------ | ------------------- | ----------------------------- |
219+
| **Fixed position** | Enabled (if no GPS) | Enter coordinates manually |
220+
| **Latitude** | `57.74213199999996` | Latitude (no trailing zeros) |
221+
| **Longitude** | `40.9780224` | Longitude (no trailing zeros) |
222+
| **Altitude** | `265` | Altitude in meters |
223+
224+
> 💡 **Coordinates**: enter without trailing zeros (e.g., `57.742`, not `57.74200`).
225+
226+
### Position Packet
227+
228+
| Parameter | Value | Why |
229+
| ------------------------------- | ----------------------- | -------------------------------------------------- |
230+
| **Position broadcast interval** | `3600–43200 s` (1–12 h) | In dense cities - 6–12 h to reduce load |
231+
| **Smart position** | `Yes` | Sends more often when moving, less when stationary |
232+
| **Smart interval** | `30 seconds` | Minimum interval when position changes rapidly |
233+
234+
> 🔐 For privacy: reduce `Precision` in channel and `Map precision`, or set fixed coordinates away from real location.
235+
236+
---
237+
238+
## ⚙️ Additional Modules
239+
240+
### Environment Module
241+
242+
| Parameter | Value | Why |
243+
| ---------------------- | --------------- | -------------------------------------------- |
244+
| **Enabled** | `Yes` | Send neighbor data to map |
245+
| **Update interval** | `14400 s` (4 h) | Minimum interval |
246+
| **Transmit over LoRa** | `No` | Don't load radio network; data goes via MQTT |
247+
248+
> 🗺️ Map will show layers "Who heard this device" and "Who this device heard".
249+
250+
### Device Settings
251+
252+
| Parameter | Value | When to Use |
253+
| ---------------------- | -------------------- | --------------------------------------------------------- |
254+
| **Role** | `CLIENT_MUTE` | In cities with >200 nodes - safe mode without rebroadcast |
255+
| | `CLIENT` | If network is small or you have good antenna/location |
256+
| **Rebroadcast mode** | `CORE_PORTNUMS_ONLY` | For large networks; `ALL` - for small ones |
257+
| **Broadcast interval** | `3 hours` | Interval for node information transmission |
258+
259+
### Timezone
260+
261+
| Parameter | Value |
262+
| ---------------------- | ----------------------------------- |
263+
| **Timezone** | `GMT+3` (Moscow) |
264+
| **Use phone timezone** | Enabled (if configuring from phone) |
265+
266+
---
267+
268+
## 🔧 Optimal Flashing Process
269+
270+
### For Heltec V4 (Bootloader Workaround)
271+
272+
Due to a Heltec V4 bootloader quirk, the standard order doesn't always work. Optimal process:
273+
274+
1. **Disconnect** battery and USB from the board
275+
2. Open [web flasher](https://flasher.meshtastic.org)
276+
3. Select device: `Heltec V4`, firmware: `2.7.13`
277+
4. Click **Erase Flash and Install**
278+
5. **Hold the `PRG` button** on the board
279+
6. **While holding `PRG`**, plug in the USB cable
280+
7. Observe: brief red flash → `USB JTAG` appears in port dropdown
281+
8. Release `PRG`, select `USB JTAG`, click **Connect**
282+
9. Wait for flashing to complete
283+
10. After `Leaving...` message, **press the `RST` button** (reset)
284+
285+
> 💡 **Note**: this process is described in [meshtastic/firmware#8543](https://github.com/meshtastic/firmware/issues/8543)
286+
287+
---
288+
289+
## 📤 First Messages Between Two Nodes
290+
291+
### Preparation
292+
293+
1. Flash **both** boards per instructions above
294+
2. On each, configure:
295+
- Same region (`Russia`)
296+
- Same channel with identical `PSK` (`AQ==`)
297+
- `Position enabled: Yes` (for testing)
298+
3. Place nodes 10–50 m apart (for initial test)
299+
300+
### Test
301+
302+
1. On first node in app: `Messages` → `+` → type text → `Send`
303+
2. On second node: incoming message should appear
304+
3. Check `Map` tab - if MQTT is enabled, both nodes should appear on map within an hour
305+
306+
### Troubleshooting
307+
308+
| Symptom | Check | Fix |
309+
| --------------------- | ----------------------------------------------------------- | ----------------------------------------------------- |
310+
| No messages | Verify channels have same `PSK` | Copy key exactly, no spaces |
311+
| Node not on map | Check `MQTT enabled`, `Map reports`, internet on phone/node | Reboot node (`RST`), wait 1–2 report cycles |
312+
| MQTT connection error | Verify `TLS enabled`, root topic | Try disabling TLS; ensure `Root topic` = `msh/RU/XXX` |
313+
| No radio connection | Check antenna, region, `Hop limit` | Attach antenna, set `Region: Russia`, `Hop limit: 5` |
314+
315+
---
316+
317+
## 🗓 What's Next
318+
319+
1. ✅ **Part 2: Practice** - unboxing, flashing, first messages (this article)
320+
2. 🔜 **Part 3: Field Tests** - urban range tests, antenna tuning, power consumption
321+
3. 🔜 **Part 4: Integrations** - Home Assistant, Telegram bridge, sensors
322+
4. 🔜 **Part 5: Advanced** - Reticulum, custom firmware, optimization
323+
324+
---
325+
326+
## 🆘 Help and Community
327+
328+
- 🗺️ [ONEmesh Map](https://map.onemesh.ru) - network visualization
329+
- 💬 [Telegram Group](https://t.me/onemesh_ru) - questions, help, city coordination
330+
- 📘 [Official Meshtastic Docs](https://meshtastic.org/docs/)
331+
- 🐙 [Firmware Repository](https://github.com/meshtastic/firmware)
332+
- 🔧 [Heltec V4 Specs](https://meshtastic.org/docs/hardware/devices/Heltec-automation/lora32/?Heltec=v4)

0 commit comments

Comments
 (0)