Use your favorite serial terminal emulator tool to access the serial COM port of your computer, and thus, Hexabitz CLI via a USB-to-UART cable. Some examples include RealTerm, Putty, HyperTerminal and SecureCRT. The configurations displayed here are for RealTerm but they are similar to those in other terminal emulators.
If you use standard FTDI USB-UART 3.3V cable for power and communication, connect the colored cable wires as follows:
- Red (VCC) to 3.3V (top power pad, i.e., corner edge pad).
- Black (GND) to GND (bottom power pad, i.e., corner edge pad).
- Yellow (RXD) to MCU TXD (top communication pad, i.e., side edge pad).
- Orange (TXD) to MCU RXD (bottom communication pad, i.e., side edge pad).
In RealTerm Display tab, select Ansi as data display mode. This mode allows you to use the BACKSPACE key to delete previous characters. Optionally, enable Scrollback and increase number of Rows to a suitable number (e.g., 32).
In the Port tab, select 921600 baudrate and open the appropriate COM port. The port will only show up after you power the module and usually it will have \VCP (virtual COM port) in its name.
Once you open the port, press ENTER keyboard key to start the communication session. You should see the CLI welcome message shown below. It tells you the ID of the module you are connected to and through which 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 default ID in the code).
Setting up Baudrate
Default baudrate for all array ports is 921600. You can change this rate with the following methods:
- Connect P1 TXD and RXD together momentarily while power-cycling the module. This will setup all array ports to 115200. Once you connect to a CLI port, other messaging ports restore their default baudrate. Note that the CLI will restore its default baudrate on the next power cycle.
- Change the value of BOS.clibaudrate parameter in the CLI using set Command. This will save the baudrate value to the emulated EEPROM so that you can use the new baudrate each time. You need to reset the module to apply the new baudrate. Note that similar to method 1, the new baudrate will apply to all ports until you connect to the CLI.
- Change the value of BOS.clibaudrate parameter in the code and call this API UpdateBaudrate(port, baudrate) to apply the new baudrate to a given port. You can also save it to 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));
If you want to restore the default CLI baudrate, you can either:
- Set BOS.clibaudrate to default value either in CLI or in 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 this firmware). You can figure out the firmware version and compile time and date using the status Command.
- If you misspell a command you can use the BACKSPACE keyboard key to delete 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 text editor but it will still work fine with the CLI. You cannot clear a character from the terminal window for example. When you press BACKSPACE, the blinking cursor will move back one step but the previous character will stay displayed. It will be removed, however, from 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 type in the command with fewer parameters than expected. If you type more than the required parameters, then extra parameters 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 type in multiple white-spaces between parameters they will be parsed correctly. However, 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. You can write in lower-case, upper-case or mixed-case and they will recognized.
- Each module is referred to 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:
- If you are broadcasting a command, replace module ID/name with the keyword all:
- 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 be assigned sequential IDs according to their distance to the module where the exploration was initiated (this module will get ID 1). Module alias name can be used anywhere a module ID is used. If you rename a module again, the new name replaces the old one. Once you rename a module, its alias name will show up 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]
- Module alias name is stored in emulated EEPROM and loaded back on each power cycle. It’s not currently shared, however, with other modules in the array.