How-To

⌘K
  2. Home
  4. Docs
  6. How-To
  8. Use the Command Line Interface (CLI)

Use the Command Line Interface (CLI)

Connection

In order to access the serial COM port of your computer, use your preferred serial terminal emulator tool (e.g., RealTerm, Putty, HyperTerminal, and SecureCRT), and reach Hexabitz CLI via USB-to-UART cable. 

The configurations below are related to RealTerm software. Other terminal emulators’ settings will be pretty similar to these steps.

If you’re using a standard FTDI USB-UART 3.3V power and communication cable, refer to the following instructions to connect the colored cable wires correctly:

  • Red (VCC) >> 3.3V (the top power pad, i.e., the corner edge pad).
  • Black (GND) >> GND (the bottom power pad, i.e., the corner edge pad).
  • Yellow (RXD) >> MCU TXD (the top communication pad, i.e., the side edge pad).
  • Orange (TXD) >> MCU RXD (the bottom communication pad, i.e., the side edge pad).

 

RealTerm software configurations

In the RealTerm Display tab, select Ansi as the data display mode. This mode allows you to use the BACKSPACE key for deleting the previous characters. Other options would be: enabling the Scrollback choice and increasing the number of Rows to a desirable number (e.g., 32).
In the Port tab, select 921600 baud rate and open the appropriate COM port. You won’t be able to select the port unless you powered the module first. It usually has a \VCP (virtual COM port) named after it.

Once you open the port, press the ENTER keyboard key to start the communication session. You should see the CLI welcoming message represented below which contains the ID number of the connected module and its matching array port. Note if the module is native, i.e., not part of an array via a fixed or explored topology, it will show up as ID = 0 (unless you change the default ID in the code).

Setting up the baud rate

The default baud rate for all array ports is 921600, but there is an ability to change this rate by the following methods:

  1. Connect P1 TXD and RXD together momentarily while power-cycling the module. This procedure will set up all the array ports to 115200. Once you connect to a CLI port, other messaging ports will restore their default baud rate. Note that the CLI will restore its default baud rate on every next power cycle.
  2. Change the value of BOS.clibaudrate parameter in the CLI using set command. This will save the baud rate value to the emulated EEPROM for using it each time. You will need to reset the module in order to apply the new baud rate. Note that the new one won’t be applied to all ports until you connect to the CLI, similarly to method 1.
  3. Change the value of BOS.clibaudrate parameter in the code and call the following API “UpdateBaudrate(port, baudrate)” to apply the new baud rate on a given port. You can also save it to the emulated EEPROM using this code (It will be loaded automatically from EEPROM on each startup):
EE_WriteVariable(VirtAddVarTab[_EE_CLIBaud], (uint16_t)BOS.clibaudrate);
EE_WriteVariable(VirtAddVarTab[_EE_CLIBaud+1], (uint16_t)(BOS.clibaudrate>>16));

For restoring the default CLI baud rate, you can either:

  • Set BOS.clibaudrate to the default value, either in CLI or in the code as shown above.
  • Initiate a Factory Reset by connecting P1 TXD to programming port RXD or to last port RXD while power-cycling the module.
  • Set all parameters back to default using default params CLI command or using the following code:
memcpy(&BOS, &BOS_default, sizeof(BOS_default));
SaveEEparams();

General Usage Tips

  • Type help anytime to view the list of commands enabled in this module (and in this firmware). You can figure out the firmware version, compile-time, and date using the status command.
  • If you misspell a command you can use the BACKSPACE keyboard key to delete the last characters and replace them with correct ones, as long as you have not pressed ENTER yet. BACKSPACE does not actually work in the terminal window as in a regular text editor, but it will still work fine with the CLI. You cannot clear a character from the terminal window, for instance when you press BACKSPACE, the blinking cursor will move back one step, but the previous character will stay displayed. However, It will be removed from the CLI buffer. If you write a new character, it will replace the old one on the terminal window, and it will be added to the CLI buffer.
  • If you misspell a command and press ENTER, it will be ignored, and you will get an error message “Command not recognized”. This will happen as well if you typed fewer parameters than expected in the command. If you type more than the required parameters, then the extra ones will be ignored. Command parameters are separated by at least one white space (SPACE key) and they will be parsed according to their order.
  • If you typed multiple white spaces between parameters, they will be parsed correctly. However, the maximum number of characters in each command (i.e., line) should not exceed 49 (it’s adjustable in the code).
  • If you hit ENTER without writing anything, the last command will be repeated.
  • All CLI commands and parameters are case-insensitive, that’s why writing in lower-case, upper-case, or mixed-case will be perfectly recognized.
  • It’s referred to each module by its ID prefixed with # (e.g. #7) or by its alias name.
  • The general format for a command is:
module.command parameter1 parameter2 parameter3

where module is module ID or name. Some examples:

#2.ping
#0.on 100
alpha.ping
North12.off
  • If you are typing local commands, i.e., BOS and module commands to be executed locally, you can remove the module ID/name prefix and type in the command directly, or replace module ID/name with the keyword me:
me.ping
ping
  • If you are broadcasting a command, replace the module ID/name with the keyword all:
all.ping
  • Module ID cannot be modified in the CLI. It is hard-coded inside the code through preprocessor directives. When exploring an array, all native modules will assign sequential IDs according to their distance to the module and wherever the exploration was initiated (this module will get ID 1). The module alias name can be used wherever a module ID is used. If you rename a module again, the new one will replace the old one. Once you rename a module, its alias name will appear between parenthesis when you ping it:
>name john
Module 0 is named john

[Press ENTER to execute the previous command again]
>name bob
Module 0 is named bob

[Press ENTER to execute the previous command again] 
>bob.ping
Hi from module 0 (bob)

[Press ENTER to execute the previous command again]
>ping
Hi from module 0 (bob)

[Press ENTER to execute the previous command again]
  • The module alias name is stored in the emulated EEPROM and loaded back on each power cycle. However, It’s not currently shared with other modules in the array.

Note: you can always disable CLI in any module so that no one can access the module and change its command, you can do this by writing this command in UserTask:

BOS.disable=ture;

Which is false by default, so it should be changed to true in order to disable the CLI command in all ports.

How can we help?