Mesh and USB commands in the CLI


We have released Particle CLI 1.40.0. This release introduces new commands for the basic mesh network management (particle mesh), as well as a number of USB utility commands (particle usb).

Please note that the new commands are currently in beta and are intended to be used by early adopters only.

Known issues, limitations and important notes:

  • Device OS 0.9.0 is required for the new commands to work.
  • It is still required to use Particle mobile apps to configure gateway devices.
  • When adding a new device to a network, the assisting device has to be connected to the host computer via USB along with the joining device.
  • The new commands will likely not work on Windows. We will release a fix for this issue in a few weeks.

A few examples:

Getting the list of USB devices attached to the system

$ particle usb list
argon1 [b43aee28c3b1e2a1a0c71e43] (Argon)
xenon1 [461d5ab513f91475c636b0b3] (Xenon)

Creating a new mesh network

$ particle mesh create my_network argon1
Enter a password for the new network [input is hidden]
Confirm the password [input is hidden]
Done! The device will be registered in the network once it is connected to the cloud.

In the above example, argon1 is a claimed device which was configured via the mobile app. The device is connected to the host computer via USB.

Adding a device to a network

$ particle mesh add 461d5ab513f91475c636b0b3 argon1
Enter the network password [input is hidden]
Done! The device should now connect to the cloud.

This command adds a device with the ID 461d5ab513f91475c636b0b3 to the current network of argon1. The CLI will automatically claim the newly added device if necessary.

Getting the list of mesh networks

$ particle mesh list
    argon1 [b43aee28c3b1e2a1a0c71e43] (Argon)
    xenon1 [461d5ab513f91475c636b0b3] (Xenon)

Removing a device from its current network

$ particle mesh remove xenon1
Are you sure you want to remove this device from the network? Yes

Reference docs: particle mesh, particle usb


Any feedback is welcomed!

Catch 22 setting up 3rd gen devices
Can't Add Another Xenon
New Windows Drivers and general availability of mesh and USB CLI commands
Timeline for Mobile App Update?

Hmm, isn’t that a bit counterintuitive?
Wouldn’t you rather add a new device to the mesh than the gateway?
Especially when adding a device to a production network, where the gateway is not free to be USB connected without interfering with the running network, that option doesn’t seem very practical.


I’ll add that to the list of current limitations. The problem is that when adding a device to a network, the CLI has to be connected to some device which is already a member that network. Eventually, we will eliminate the need to maintain this extra connection by talking to the gateway device via the cloud.


I am echoing @scruffr comment. Understanding that this is a stepping stone to devices being able to programmatically join a mesh network e.g. Mesh.join(meshname, meshpassword) - it would still seem to be a lot easier/more practical to use the mobile app for now.

With the $ particle mesh list - useful but not as useful as the console. It could have been more useful if the gateway device was identified (or is it always the first in the list?) and the connection method added - I known it is implicit in the device type.

When are we going to get $ particle mesh network remove?


“particle mesh add 461d5ab513f91475c636b0b3 argon1”
" This command adds a device with the ID 461d5ab513f91475c636b0b3 to the current network of argon1 . The CLI will automatically claim the newly added device if necessary."

i kind of took it to me adding the device to the network “of” argon1. to me it means the device gets added to the mesh network which has argon1 as gateway. i’m most likely wrong.

anyway, thanks for the update.


This is how I’d read it for an Argon, but the admittedly sparse docs would suggest that it could be any device that’s already part of the network

However, the distinction where to use the device ID vs. device name (or if it doesn’t matter which) is not clear at all in these docs.


Okay, some advice please. I think this is a common use case, but I can’t see how others have dealt with it. Having done development work on a 2 Xenon mesh using an Argon as gateway (to minimise data costs) I now want to change over to the production mesh based on a Boron gateway. What is the simplest way of doing this?

My understanding is that a mesh must have a gateway, but cannot have 2 gateways. The ideal case would be if I could have the argon and boron on the same network and just turn one off and power the other one up, but this doesn’t seem to be possible. Am I wrong?

The alternative seems to be to remove each of the Xenons from the Argon network and add them to the Boron network. This would be best done with the CLI as described here, I assume. A reasonable approach for 2 xenons, but what about when the mesh grows to ten Xenons.

Or, can I just remove the Argon from the existing network and then add the Boron? This doesn’t seem to be possible from my reading of the forum.

Thanks in advance.


That is only currently so. The planned High Availability (HA) Mesh which will allow multiple gateways - but no ETA for that yet.

Unfortunately for the time being you’d have to reconnect each individual Xenon to he Boron separately.

However, this step is not explicitly required

That will implicitly happen when you assign the node to a new network.

You could just try it, although I doubt it’ll work.


That will implicitly happen when you assign the node to a new network.

Thanks! That helps. At least it will only be one step, I thought I would have to remove the Xenon from the old network separately.

Bring on HA :slight_smile:

I am also stuck on strings. String vs char vs c_str is doing my head in and am mindful of your warning on strings @ScruffR. I will post a separate thread on that when time permits… (deadlines grrr)


Are there CLI commands to publish and subscribe to mesh only topics? Particle.publish() goes against the Cloud API, but I’m looking to use the CLI to run something like Mesh.publish(). There doesn’t appear to be anything like this in the documentation, unless I’m missing something. Thanks.


Nope, since your computer that would issue the event is not part of your mesh network so it cannot emit events that originate and terminate within mesh only.

You could, however, have your gateway relay cloud events

void relayEvent(const char* even, const char* data) {
  Mesh.publish(&event[2], data);                      // strip off the 'm_' prefix and relay to mesh

void setup() {
  Particle.subscribe("m_", relayEvent, MY_DEVICES);  // any event starting with 'm_' should be relayed


Makes sense. That’s a great workaround! Thanks!

Okay, so I have the following setup:

//in Setup()
//Local PubSub Topics
  Mesh.subscribe("all-lights-on", meshTurnAllLightsOn);
  Mesh.subscribe("all-lights-off", meshTurnAllLightsOff);

  Particle.subscribe("m_", relayMeshEvent, MY_DEVICES);  // any event starting with 'm_' should be relayed

And the following handlers defined:

void relayMeshEvent(const char* event, const char* data) {
  Serial.println("relay event received");
  Mesh.publish(&event[2], data);                      // strip off the 'm_' prefix and relay to mesh

void meshTurnAllLightsOn(const char *event, const char *data)
  Serial.printlnf("event=%s data=%s", event, data ? data : "NULL");
  togglePower("on", config.lightId, brightness);

void meshTurnAllLightsOff(const char *event, const char *data)
  Serial.printlnf("event=%s data=%s", event, data ? data : "NULL");
  togglePower("off", config.lightId, brightness);

I can verify that my relay event is firing and the value of &event[2] is stripped to all-lights-on.
However, I don’t see anything outputting in through Serial from the meshTurnAllLightsOn() function. Any ideas why the handlers aren’t firing despite the mesh topic being subscribed?