MeshCore: Generate New Private Key
By Eric Hendrickson
Avoid first-byte collisions in trace path and manual path tools
MeshCore’s trace path tool is essential for understanding how packets travel through the fascinating ether of our beloved multi-hop mesh network. Trace path helps us understand not only the path but the signal strength at each hop as well.
In a densely-populated mesh, packets often can follow several different paths but not all are ideal. This is where the trace path tool really shines. By allowing us to personally inspect individual paths of our choosing, we can often find optimizations with just a little time and effort. If you’re familiar with the trace path tool, you know that paths consist of a comma separated lists of two-digit hexadecimal numbers which represent the first byte of each device’s public key.
The Network is Running Just Fine
This first-byte identifier works just fine until you have two nodes with the same first byte, thus revealing MeshCore’s ugly little secret: The first-byte collision. It is quite common in practice, and one of MeshCore’s more challenging design compromises. One proposed solution would be to use two bytes in the address, and while that would solve most of the addressing problems, it would create a potentially bigger problem: Taking that byte away from the path and giving it to the address reduces the number of available network hops from 64 to 32 and that’s not a trade-off I’m willing to accept just yet.
This is not a routing failure and it’s not an issue with RF collisions or “doubling”. No, this is purely a MeshCore identity issue. These duplicates will start to appear as your mesh grows and fills out. Rest assured MeshCore’s underlying packing switching engine is dutifully looking at the entire address, as it should, and as it was designed to do. This is purely a troubleshooting, identity, and manual path routing problem.
The Contact List Workaround
The only working solution to this problem is repeated pruning of one’s contacts list in an effort to remove the conflicts. This works temporarily, but it is reactive, time consuming, does not scale well, and in a big mesh is not very practical.
Why Generating a New Private Key Helps
A node’s identity in MeshCore is derived from its public key. Generating a new private key also makes a new public key and thus refreshes the node’s identity with a new address and a new first byte.
The above chart, from https://analyzer.letsmesh.net/nodes/prefix-utilization, is filtered for the San Francisco Bay Area Region and clearly illustrates the duplicates problem we have right here in the valley. We see a number of duplicates but we also see a reasonable number of available addresses. There’s a lot of opportunity here to get things cleaned up.
Is There a Fix for Duplicate Keys in MeshCore?
There’s actually a pretty slick solution to this problem, thanks to Adam Gessaman, and his generous contributions to the growing world of MeshCore productivity and utility tools. His mc-keygen web tool lets you specify your own public key first byte then it cranks out private/public key pairs until it finds a match in the first byte of the resulting public key. This process usually takes less than a second to complete and chews through about a hundred or so keys in the process. This is brute-force key harvesting in action. Thank you, Adam, for this very effective tool.
To utilize mc-keygen, first click one of the green squares on the Analyzer.LetsMesh.Net website. These are linked directly to mc-keygen, where it fills in the two-digit first byte address for you. From here, it’s just a matter of verifying the address is correct and pressing the the Generate Key button.
When You Should Regenerate a Keypair
The best time to regenerate a key pair is immediately after a fresh flash, before the node has ever broadcast its ID. At that point, the node has no history and no one else has learned its identity. If it’s a duplicate, change it before you allow it to send a flood broadcast.
The next best time to change keys is whenever you discover that you have a duplicate that’s consistently causing you or your friends some trouble. Once a node has been active, regenerating its key will cause it to reappear as a new identity. This will result in duplicate entries in other operators’ contact lists, but this is not a big deal. The old entry simply goes quiet and can be removed from their contacts list.
Installing a Custom MeshCore Key in Companion Device
After you’ve generated a custom key with mc-keygen, and you have your new public and private keys, the next step is applying them to your MeshCore companion device.
Connect your phone to the MeshCore device using a USB-C cable or Bluetooth, then open the MeshCore mobile app. Confirm the device is connected before proceeding. From the main screen, tap the settings gear in the upper right.
Scroll down and select Manage Identity Key. This screen allows you to input the new private key you just made. Copy the private key generated by mc-keygen and paste it into this field. Make sure you paste the entire 128-character private key. Do not paste the public key.
Tap Import Private Key, then tap the check mark in the upper right to save the change. This step is required to save. If you exit without saving, the new key will not be applied.
Return to the main screen and verify the update. The public key displayed should now begin with your selected prefix. This confirms the new identity is active and that your node can be uniquely addressed by trace path and manual path tools.
Applying a Custom Key to a MeshCore Repeater or Room Server
Start by connecting the repeater to your computer using a USB serial connection. Once connected, open a terminal session using the MeshCore web console or any standard serial terminal application. The MeshCore web console provides a convenient interface and includes a built-in command reference, which can be helpful when working with repeater configurations.
At the console prompt, set the private key using the following command:
set prv.key <your_private_key>
Replace <your_private_key> with the full 128-character private key generated by mc-keygen. Be sure the entire key is included. This command takes effect immediately and replaces the existing identity key on the device.
After setting the key, verify the change by checking the device’s reported public key in its status or settings output. The first two characters should match the prefix you selected during key generation. Once confirmed, the repeater will advertise its new identity to the MeshCore network and can be uniquely addressed by trace path and manual path tools.
As with companion devices, keep a secure backup of your keys. If the repeater firmware gets flashed or the configuration is reset, that key can be used to restore the node’s identity.
Verification and Common Issues
If the new key does not appear, confirm that you saved the change using the check mark. Most failures are caused by skipping this step or pasting an incomplete private key. If the app fails to detect the device, reconnect the USB cable or Bluetooth link and try again.
After applying the key, verify that trace path and manual path operations resolve cleanly and that your node appears on the MeshCore network with the new identifier.
Keep a secure backup of your private key. If the device is ever re-flashed or reset, that key is required to retain the same node identity.
Final Thoughts
As MeshCore networks grow, the limitations of human-facing diagnostic tools become more visible, and while not necessarily a flaw in MeshCore—these issues are a result of design decisions made early in the development process. Will we ever see changes that allow more detailed addressing? Maybe. But for now, managing collisions by generating new key pairs is a valid and useful option that will make using the Trace Path and Manual Path tools work better for everyone. Ongoing maintenance will be required.
