Write obnizOS by obniz-cli


obniz-cli is obnizOS writing-only software that is delivered by npm and can do the following mainly.

  • obnizOS writes
  • Sign in to the cloud and create a device
  • Writing DeviceKey by specifying obnizID.
  • Network settings such as Wi-Fi

With obniz-cli, you can do everything from generating devices to setting up WiFi with a single command, so it's easy to generate a lot of devices.

The following command creates the device (with instructions) => writes the OS=>WiFi configuration.

obniz-cli os:flash-create -p /dev/tty.USBSERIAL

Preparing obniz-cli

obniz-cli writes by using the official tool "esptool" provided by Espressif.

You need Nodejs12 or later and pip to use it.
You can find out how to use it from here at https://github.com/obniz/obniz-cli.

First, install it with npm. From the shell, run the following

npm i obniz-cli -g

Next, install esptool.

pip install esptool

The software is now ready to go. Connect the device you want to write the program to to your PC via serial.

About the driver

You may need a USB driver on your machine to transfer programs to the processor (DevKitC and M5Stack are often required), in which case https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers

This driver is often used by the ESP32 development board, so install it as needed. (I'm just saying it's a high possibility. Please check the manufacturer's driver information for the exact one)

The available serial ports can be checked with the following commands

obniz-cli os:ports

Create a device with obniz-cli

Sign in

First, you need to sign in to the OBNIZ cloud.

obniz-cli signin

When you authenticate to obniz-cli, you will be signed in and the completion will be displayed in the shell.

Generating and Writing

The writing OS and generate a device in your account is done with the following command (please use your own serial port name)

obniz-cli os:flash-create -p /dev/tty.USBSERIAL

By default, obnizOS is "obnizOS for ESP32" the latest one to be downloaded.

Selecting obnizOS by hardware

If you don't specify it, then the option "obnizOS for ESP32" is specified. You can install the dedicated obnizOS by specifying --hardware. The display and other features will be available from the start. For example, with obnizOS for M5StickC

obniz-cli os :flash-create -p /dev/tty.USBSERIAL --hardware m5stickc

hardware can be selected from the following

Device OS --hardware
M5Stack Basic obnizOS for M5Stack Basic m5stack_basic
M5StickC obnizOS for M5StickC m5stickc
ESP32, ESP32-PICO, ESP32-WROOM32, DevKitC obnizOS for ESP32 esp32w

Device key setting failure behavior

Wi-Fi settings are saved in a file, and the settings are made when you specify them with arguments as above.

After the device is generated, the DeviceKey is set for the device.
If you fail to do so, you will be asked if you want to write the last number set for writing by executing the same command, so you can write it if you answer YES.
Also, since the generated device already exists in your account, you can also write to it with the following obnizID

Automatic Setting

The following settings can be made at the same time when writing the OS

  • Network settings such as Wi-Fi
  • description settings
obniz-cli os:flash-create -p /dev/tty.USBSERIAL --description "Plant A" --config ./wifi-config.json
Argument Description Setting Example
--description Description on Cloud --description "Plant A"
--config Network Setting --config ./wifi-config.json

Writing a pre-generated device

Here's how to write a device in your device list. Sign in and write with obnizID.

obniz-cli os:flash -p /dev/tty.USBSERIAL -i 0000-0000 --config ./wifi-config.json
Argument Description Setting Example
-i obniz ID on Cloud -i 0000-0000

How to delete

You can also delete and initialize obnizOS, including the device key, if you make a mistake in the configuration.

obniz-cli os:erase

Configuration from a terminal

It is also possible to configure devicekey without using obniz-cli.
For devices that only write to obnizOS, it can be configured via the terminal.

First, you need to set up a serial communication with the device. You can communicate with your terminal app or with the following python modules

python -m serial.tools.miniterm /dev/tty.SLAB_USBtoUART 115200

The device is waiting for the device key to be entered when communication is started.
If the following message appears by pressing the Enter key, obnizOS is running normally.


In addition, if you reset the device while it is communicating, the following message will be displayed.

obniz ver: 2.0.0

In this state, we are waiting for the device key to be written.
The device key downloaded from the cloud is a string that looks something like this


Just type it in and press the enter key to complete the setting.
Once completed, it is time to set up the network.