Netbeans 16 with Tomcat 8.5 on Windows

Getting Tomcat 8.5 to work with Netbeans 16 on Windows is maddeningly difficult in large part because the windows service installer for Tomcat doesn’t set the defaults that Netbeans needs.

If you’re on this page, it’s because you’ve been frustrated with it too. The magic formula to install tomcat correctly seems to be:
1. Set the server shutdown port to the default expected by Netbeans (8005) not the default (-1)
2. Add a Tomcat Administrator (e.g. user name=Tomcat password=Tomcat
3. Add manager-script to the Roles

Raspberry Pi alternatives

Libre ROC-RK3328-CC Single Board Linux Computer

When folks need a small embedded linux machine for control applications, a Raspberry Pi is usually the first thought. I’ve made good use of Raspberry Pi Zeros and 3Bs but have been reluctant to adopt the RPi 4 due to the apparent need for active cooling, high power consumption, very poor availability, and high pricing (it makes little sense to use an RPi when you could use a much more powerful x86-family platform).

With RPis out of stock for months and being scalped everywhere, I decided to try a Libre Computer ROC-RK3328-CC which is footprint/form factor compatible with the Raspberry Pi and can run Ubuntu, Raspberry Pi OS, Armbian, Debian, Android, and many other OS. The docs are here. The board comes in two versions: 2GB for $45 and 4GB for $55 – those prices are with free one-day shipping via amazon prime and they are available immediately. I bought the 4GB version which is 4x the memory of an RPi 3B+; the memory is also DDR4 vs. the DDR3 used on the Pi. The board is easily passively cooled; I bought the custom heat sink ($10) although any similarly sized heatsink should work fine.

I tried Ubuntu desktop but was disappointed by the bloat and installed Raspberry Pi OS (a Debian derivative) instead and am very happy with it; I installed the desktop (not lite) version. The board is DIN-rail mounted using this high-quality mounting solution. It runs several minicom sessions monitoring/logging other embedded boards as well as a Postgres database and Java backend data collection application. Even over TightVNC, it feels snappy and doesn’t break a sweat (stays between 45 and 47C); it is using less than 1/4 of the available RAM (but would have used nearly all of the RAM on an RPi3).

Other upsides: 4K video (mainly of value for HTPC applications) and USB 3.0 – much more important because it makes it worthwhile to connect an external SSD which will be much faster and more reliable than uSD storage. The main downsides relative to the Raspberry Pi are: no WiFi/Bluetooth and no Pi-compatible camera connector. I didn’t need those for my application (which is rack-mounted and connected to Ethernet), but if you need either, you can easily solve them via USB connection.

For storage, I use Sandisk Extreme uSD cards. 64GB costs $11 and is plenty of storage for my application (I’m only using 6%); if I need more, storage or speed, I’ll use an external M.2 card connected via USB 3.0. Note: there is a huge difference in performance and reliability between SD storage cards used in RPi applications; some cards won’t work at all, some will work but at half the speed of others (see this performance comparison). I’ve tried a bunch and settled on the Sandisk Extreme which offer good speed with a cost only slightly higher than lesser cards; the benchmarks bear this out. If I were doing something more disk-intensive, I’d consider either a board with a native M.2 interface (like the Odroid M1) or an x86 board with a native SATA or M.2 interface.

Note: uSD cards aren’t meant for frequent writing (as in linux logs), so if you want your card to last, I strongly recommend using a utility like log2ram that creates a small RAM disk for the /var/log partition (you can add others) and then periodically flushes that partition to SD storage. This will dramatically lengthen the life of your SD card; see here for more info.

Home Network VLANs

Cyber security is a growing problem and the rapid growth of IoT is only making things worse. Many homes are now inundated with “connected” devices, many of which are vastly less secure than your typical home PC (which itself is fairly insecure). Connected devices usually have much smaller and less capable microprocessors, making it harder to implement robust security mechanisms. Their software also receives far less scrutiny than the software in popular operating systems and they typically receive software updates infrequently. With so many devices online these days, from thermostats to cameras to appliances to streaming sticks, it’s just a matter of time before those are hacked and if those devices are on the same network as your computers and document/photo storage, all of those are at increased risk.

One strategy to help lower risk is to create separate networks in your home for the devices containing sensitive data (taxes, family photos, documents, etc.) and for your internet-enabled devices. For example, you might have separate networks for:

  • Home computers and storage
  • Printers
  • Guests
  • Streaming devices (e.g. Amazon Fire Sticks and Fire ReCast or TiVos or …)
    that need to communicate with each other and the internet
  • IoT devices (cameras, appliances, thermostats, etc.) that only need to communicate
    with the internet.

There are two main ways networks are formed these days: wired (Ethernet) and wireless (WiFi). Most modern WiFi access points let you create a separate isolated guest network that has its own ssid and where the firewall rules allow each host on the network only to access the internet; they can’t access each other or your home network. Providing separation and isolation for your wired network is a little more complex.

The easiest way to do separate your wired devices is to put them on separate networks connected by a router. You can create separate networks by physically wiring them separately, with each network only connected to the router, but that’s often inconvenient;
you may have a streaming device and a computer in the same room and you don’t want to run two wires. Another approach is to use intelligent Ethernet switches that support a feature called Virtual LANs (VLANs).

WIth VLANs, you create separate networks by assigning each network a number and then controlling which network(s) each port on your switch participates in (they can participate in more than one). Lots of companies make intelligent (aka managed) switches including Netgear and Ubiquiti. Netgear offers an inexpensive line of semi-intelligent GbE switches that support VLANs called ProSafe Plus. These can often be had on eBay for $20. Ubiquiti makes a more feature-rich line of switches, part of their UniFi series and their 5-port Flex Mini switch is a strikingly good value if you buy a 4-pack (around $29/switch…unheard of for a fully managed switch).

With NetGear switches, you *must* update the firmware to the latest version before using it; older firmware versions have serious security vulnerabilities. You configure the switch using its web interface. Under VLAN, select 802.1Q, then Advanced. Under VLAN Configuration, enter a unique VLAN ID for each network you want to create. VLAN 1 is the default network. Then under VLAN Membership, select which ports on the switch belong to which VLANs. Ports can be configured as Tagged or Untagged. Select Tagged (‘T’) for the ports that go from your switch back to the router (or another switch). Select Untagged (‘U’ for the ports that go to a computer/device/appliance. The Tagged port that goes back to your router should be a member of every VLAN. The Untagged ports that go to your devices should typically be members of only one VLAN. Finally, under Port VID, set the Tagged trunk port to use a PVID of 1 (main network) and then change each port that participates in a dedicated LAN to the number of its VLAN.

Consider an example: a 5-port switch (NetGear GS105eV2) is connected as follows:

  1. Trunk port (uplink to the router) – Tagged, member of VLANs 1,2,3
  2. PC you want on your main network – Untagged, Member of VLAN 1, PVID=1
  3. Streaming device – Untagged, member of VLAN 2, PVID=2
  4. DVR – Untagged, member of VLAN 2, PVID=2
  5. IoT device 1 (e.g. IP Camera) – Untagged, member of VLAN 3, PVID=3

The streaming device and DVR are both on VLAN 2 so they can communicate with each other as well as accessing the internet through the router. The IoT device is on VLAN 3 so it can only access the internet through the router; it cannot access the Streaming devices or the PC. This is important because if the IoT device is hacked, the hacker has not gained access to your home network.

The switch connects to a router (possibly going through other switches). The router must be configured to do the following:

  • Create a network for each VLAN. For example
  • A DHCP server should be configured for each VLAN
  • If the router contains a switch, create a virtual interface for each VLAN on the switch
  • Create firewall rules that determine how traffic can flow into, out of, and between each LAN (usually just into and between/local). For example, VLAN1 should not allow incoming traffic from the internet unless it is in response to traffic that originated on VLAN1. VLANs 2, 3 should only allow incoming traffic from VLAN1 or in response to traffic that originated on VLAN2 or VLAN 3 respectively.
  • If you run a server at home, it’s best to put it on its own VLAN and create firewall rules that only allow incoming traffic from VLAN1. Then use port forwarding on the firewall/router to bypass the firewall rules for specific TCP ports (e.g. 80, 443).

If your network is large, document it using yEd or similar.

Git and SVN

OK, I know that tool wars are for noobs, but this is going to be a rant.

I’ve been doing software development for decades and have used a lot of version control systems. I’ve been particularly fond of the rcs/cvs/svn series that has been in use continuously since the early 1980s. That line of version control systems has grown steadily and incrementally, adding functionality while retaining compatibility. SVN is now a very mature and easy to use version control system.

Along came git. Git has become immensely popular, in large part because software development is an industry dominated by the young. The young have no history to build on and so don’t understand the value of continuity and compatibility. To them, newer is always better. They are also remarkably tolerant of kluged software, often conflating excessive complexity with “power”.

Git has some clear benefits, most notably the local repository which effectively buys you a 2-tier commit structure. That’s good and SVN should develop a similar concept. Git is also very good for its intended use case: distributed project development with no central control (i.e. many open-source projects). Git is particularly nice when some of the developers have limited internet access. However, I find git problematic for a host of reasons that are rarely discussed. The biggest issue is that I have never worked on a project using git where users didn’t get into trouble. By trouble I mean losing work or having to find a git guru to help them be able to continue working. I’ve never seen that happen with svn. Never.

Moreover, one of the principle git criticisms of svn (the central repository) is actually the way most companies want to work. Central repositories live in secure data centers, are automatically and regularly backed up, and allow easy and fast access control so when a contractor/employee/etc. leaves, their access to the repository can be closed immediately. It’s why GitHub is so popular: it’s a central repository.

Git evangelists flood the internet with a-git-prop, much of it wrong or severely outdated. GitHub is also a massive proponent of git, pushing it mercilessly. There is no similar entity evangelizing for SVN and so the sheer force of marketing has been driving a lot of git’s success, but here are some sober analyses that present the other side of that coin:

Ultimately, both git and svn are mature version control systems and no serious software projects would fail because they chose one over the other. However, for those finding this page and interested in picking a version control system, you might do well to to read some of the links above to get a more balanced perspective before making your choice. I use git when I must, but given the choice, I use svn.

For SVN users interested in git, here’s a useful article:
Git for Subversion Users (

Big Buddy portable heater

As the pandemic re-surged this Fall, we started finding socially distanced outdoor get-togethers getting a little chilly. So I bought a Mr. Heater “Big Buddy” portable propane heater to help extend the season.

Mr. Heater Big Buddy

In the process, I’ve learned a few things about propane heaters I’ll share below:

  • Gas or Electric Heat: Propane heaters are characterized by their heat output in BTUs; electric heaters are typically characterized by their power consumption in Watts. You can convert electric power consumption to BTUs by multiplying it by 3.41. So a 1500W heater (about as big as you can put on a typical circuit in your house) will generate the equivalent of 5115 BTUs. For comparison, the Big Buddy heater has 3 output settings: 4000, 9000, and 18000 BTU. A typical propane patio heater generates 48000 BTU or more. Bottom line: propane heaters can generate much more heat than electric heaters. An electric heater is probably insufficient for outdoor heating.
  • Gas vs. Electric Cost: at typical electricity costs, a 1500W heater will cost under $0.22/hour to run. Exchanging an empty 20lb propane tank for a filled one costs about $20. 1lb of propane will run a Big Buddy heater on low for around 5.5 hours so the cost to run is around $0.18/hour. Note: if you use disposable 1lb propane camping cylinders instead of 20lb refillable tanks, the propane cost is much higher…see more below.
    Bottom line: heating with propane can cost about the same as with electric.
  • How much heat: I should start by saying that I like things warm. It’s also really tough to heat a substantial area outdoors since the heat dissipates into the environment so quickly. Anyone with a fire pit knows that it’s only hot within a few feet the pit. In our early trials, the Big Buddy on high output made a 55 degree day acceptable when we were outdoors and fairly close to it (2-3 feet). I doubt it will be enough when temperatures drop below 50F; that probably will require the bigger patio heaters (and even then, not if it’s windy). I expect the Big Buddy would heat any enclosed and properly ventilated space (e.g. a garage with ventilation) fairly quickly even on very cold days. There are lots of testimonials to that effect.
    Bottom line: Good for Spring and Fall evenings outdoors and for emergency indoor heat (see more on indoor use below).
  • Getting Propane: heaters like the Big Buddy can run on the super common 20lb refillable propane tanks used for outdoor gas grills as well as on one or two 1lb “camping” propane tanks. The camping tanks are usually disposable (DOT 39) and are *much* more expensive. At Home Depot and Lowes, 1lb disposable tanks cost around $5.50 each so heating using them costs around $1/hour (at the low-heat setting). Obviously the 1lb tanks make the heater much more portable.
  • How long will a tank last: propane heaters can generate a lot more heat output, but at their higher outputs, they consume a lot of propane. At high output (18K BTU), the BigBuddy consumes roughly 1lb of propane per hour, so it will cost roughly $1/hour when run from a 20lb tank and more than $5.25/hour when using disposable 1lb tanks. The larger 48000+BTU patio heaters can get expensive to run (several dollars/hour) even when using refillable tanks.
  • Refilling 1lb tanks: people try to save money by re-filling disposable 1lb camping cylinders from 20lb refillable tanks. There are loads of gadgets on Amazon specifically to do this and tons of youtube videos showing how. This is a BAD IDEA. Those cylinders are regulated by the US Department of Transportation (DOT) and they make it very clear that this is dangerous and you should not do it. They even made a video…see here. There is only one company that appears to make a legally refillable 1lb propane tank: Flame King (see here). I suspect they have a patent. You can get them at Lowes and elsewhere, but they are out of stock everywhere. A nice video on the refillable cylinders is here.
  • Indoor Use: according to the manual (and everything I’ve read), the Big Buddy can be used indoors for emergency use only (i.e. if your heat is out due to a power outage). There are some caveats: you can only use it indoors on low or medium settings (depends on where you use it: bedroom, bathroom, etc.). You need to crack a window for ventilation and you shouldn’t sleep with it on. You shouldn’t have a 20lb cylinder in your house so you need to use it with 1lb cylinders indoors. I wouldn’t run a combustion heater indoors without a Carbon Monoxide monitor in the same room (I have these anyway since our house is heated by natural gas).

  • Adapter hoses: if you’re using the Big Buddy outdoors, especially in a fixed location like a patio, you’ll probably want to use it with a 20lb refillable tank both for cost and convenience reasons (you won’t constantly be replacing 1lb cylinders). Mr. Heater makes an adapter hose that you can use with a standard 20lb tank. NOTE: the Mr. Heater hose is made of a special material that won’t leech oil into the propane and eventually clog (ruin) your heater. If you use a 3rd party hose, it will be cheaper and more flexible, but you *must* use it with an oil filter (the manual provides the part number) and you must replace that filter annually (it fills with oil and then stops working). I’m using it with a 20lb tank and the hose.
  • Stove fan: the Big Buddy used to come with a built-in battery-powered fan to help circulate the warm air. They don’t come with the fan anymore; I heard it was due to tariff restrictions. A number of people have added stove fans to their Big Buddy (lots of youtube videos) and I really like the idea. A stove-fan is a heat-powered fan (uses a built-in thermo-electric generator that converts a heat differential into electricity) so no batteries; they’re meant to sit on top of a wood-burning stove. People use a Dremel (rotary tool) make a notch in the fan body that will let it lock into the top of the Big Buddy grill. I’m going to look into that (make sure it’s safe and that the heater won’t destroy the fan); there are loads of stove fans on amazon.

Ultimately, I like the Big Buddy; it is well made, portable, and does most of what I wanted. I like that it can be used indoors as an emergency heat source and outdoors to extend the season a little. However, if you plan to entertain much outdoors during cold weather, you probably will want something bigger (a patio heater)…and be prepared to go through a lot of propane (fine with 20lb cylinder, not so fine with 1lb cylinders). In cold weather, the Big Buddy helps if you’re close to it (like 1-2 feet away), but don’t expect to be outdoors in shorts during the winter. An electric blanket/throw is actually the best solution.

Stay safe and warm!

SDG1025 Waveform Generator TCXO Hack

I have some low-cost Chinese arbitrary waveform generators for analog design/test work below ~25MHz. They are not lab grade, but they are inexpensive and offer a rich feature set if you can live with their warts. If you’re not familiar with waveform generators, this is a good introduction.

This post examines an upgrade to the Siglent SDG1025 (see: datasheet, user manual), service manual). One of the main shortcomings of this generator is that it uses a basic crystal oscillator as its frequency standard which delivers around 10ppm of frequency accuracy at room temperature and might be as bad as 50ppm. While that’s fine for many applications, Siglent includes a spot on the main board for a TCXO so you can upgrade this to 0.1ppm accuracy for under $20. You need to remove the crystal and add the TCXO and one jumper wire; see how-to links: here and here.

After installing the TCXO, I tested the SDG1025 accuracy using its frequency counter feature to measure a signal from a Marconi 2025 RF signal generator which was slaved to a rubidium frequency standard (in my Anritsu spectrum analyzer). A few things to note:

  1. The frequency accuracy was improved to 0.1ppm as advertised
  2. The frequency counter input requires a strong signal: with +10dBm input, it was accurate only to 12.5MHz; with +13dBm input (the max my RF sig gen can output), it could count accurately through 27.5MHz. The manufacturer specifies it to 200MHz.

Of the two low-cost waveform generators I own (Rigol DG1022 and Siglent SDG1025), I prefer the Rigol, but both are useful toolsand the TCXO hack certainly improves the SDG1025 frequency accuracy.

Some useful links:

12.5MHz max counter frequency
Can’t measure 13MHz
Can’t measure below 20kHz accurately
Can’t measure below +10dBm

GE Microwave Repair

I bought an over the range GE microwave (model JVM3160) oven less than 4 years ago. It was a bear to install, so I was pretty disappointed this week when it started blowing the circuit breaker each time I tried to use it. I really didn’t want to have to install another oven. Fortunately, it turned out to be a defective door-closure switch and an infuriatingly bad design.

First, the design problem: microwave ovens have small electronic switches to detect whether the door is closed and prevent the oven from turning on if it is not (for safety reasons). Unbelievably, GE decided that blowing the fuse is a good way to prevent the oven from turning on. While that is technically true (it does stop the microwave), it’s a ridiculous way to do it since it gives no indication of what’s actually wrong and could create a much greater hazard if the home’s wiring, fuse, or circuit breaker were inadequate. Combine this with use of cheap switches that fail within a few years and I question whether I should ever buy another GE product.

Thank goodness for the internet because this turns out to be a common problem and others had figured it out. After disassembling the front panel (something you can do easily without removing the oven from the wall), I found that one of the three door detect micro-switches was indeed not working. I removed, repaired, and replaced the switch and the microwave works. I suspect the switch will fail again, but replacements are inexpensive and widely available so next time I’ll know what to do.

If you have a GE microwave that’s blowing fuses, and are comfortable with basic electronics, this youtube video explains clearly how to access the microwave’s electronics without removing the oven from the wall, how to test the switches, and how to remove the switch assembly for repair.

Update: the original switch did indeed fail again after a few months, so I replaced it with a new switch purchased on amazon here and the replacement has worked like a champ ever since.

Disclaimer: It should go without saying, but microwave ovens use high voltages; you should never open or work on any appliance without unplugging it and knowing what you are doing. Although it is not exposed in this repair, microwave ovens also contain a high voltage capacitor that retains a dangerous charge even when the oven is unplugged. If you don’t know what you’re doing, play it safe and call a repair professional.

Hyper-V Serial (COM) Ports

Virtual machines (VMs) can be handy for all sorts of reasons; for example, I may need a machine running Windows 7 to support legacy development tools. I can create a VM running Windows 7 on my host machine that’s running Windows 10. Windows 10 comes with Hyper-V (similar to VirtualBox and other virtualization environments) which lets you do this quickly and easily.

However for embedded development, the virtual machine needs to be able to talk to the target and unfortunately, Hyper-V doesn’t directly support mapping virtual COM ports on the VM to physical COM ports on the host machine. Fortunately, Tim Howard wrote a nifty open source utility: COMpipe that lets you do this pretty easily.

To use it, in Hyper-V Manager, select your VM, choose Settings, choose COM1, then named pipe and give the pipe a name (e.g. wm3com10).

Then launch COMpipe on the host machine in a Command window (needs to have administrator privilege), specifying the physical COM port and the named pipe. For example:

COMpipe.exe -b 57600 -c \\.\COM10 -p \\.\pipe\wm3com10

At that point, you should be able to open COM1 in your VM using your favorite serial terminal software (TeraTerm, PuTTY, whatever) and communicate with the device that’s actually connected to COM10 on your host machine. Thanks Tim!!!

Embedded Systems CLI

When I develop an embedded system, one of the first things I implement is a command-line interface (CLI) which is invaluable for unit testing. It doesn’t take a lot of code to make a fairly sophisticated interface that allows you to type commands and get responses just like a unix or windows/dos command shell.

When I am developing in EmBitz (my favorite microcontroller IDE), for STM32 microcontrollers (my favorite microcontrollers), I use an STLinkV2 (or clone) to allow me to load software into the target and debug it easily. EmBitz provides a wonderful additional feature called EBMonitor that hooks _write() and allows you to redirect standard input and standard output (e.g. printf) over the STLinkV2 and display it in a console window within the development environment. This means you don’t need a serial connection to your target to access the console. See my previous post for more information on using EBMonitor.

However, you often want the CLI to be available for non-developers (e.g. users) using a serial connection via a USB-to-TTL dongle or a USB-to-TTL serial converter built into your target such as the CH340G or HT42B534 into the target. Creating a serial UART console is easy too; you just need to implement your own _read() and _write() functions that usually look something like this:


// Function called by stdio to send output to stdout
int _write( int fd, char* buf, int len )
    int i;
    for(i=0; i<len; i++) {
    return i ;

// Function called by stdio to read data from stdin
int _read(int const fd, char* buf, unsigned buf_size)
    int nRead = 0;
    do {
        int ch = uart_get_char();
        if ((ch != EOF) && buf) {
           buf[nRead++] = ch;
    } while ((ch != EOF) && (nRead < buf_size));
    return nRead ? nRead : EOF;


and uart_getchar() and uart_putchar() are functions that read/write a character from/to the UART…trivial for polled output or a little more complicated if you want it interrupt-driven (which you do). Once you’ve written this, then you can just #include <stdio.h> in your other modules and use printf() for formatted I/O.

Notice the use of the #ifndef USE_EBMONITOR to wrap _write(). I do this so I can use EBMonitor for debug builds and UART for release builds. EmBitz supports two targets by default: Debug and Release. For the Debug target, I define USE_EBMONITOR under:
Project -> Build Options -> Compiler Settings -> #defines

For the Release target I don’t define EBMONITOR:

Writing interrupt driven UART code is beyond the scope of this post, but there are loads of examples and tutorials online. When implementing a CLI you’ll probably want to do some processing of characters as they are received in the ISR. Typically, you’ll store them in a command buffer and then set a flag (e.g. cmd_ready) when a carriage return is received to indicate that there is a command ready to be processed (don’t process commands in interrupt time; just poll the flag in your main loop and clear it after processing the command).

I usually have a command interpreter module that creates a linked-list of commands and their associated functions. The structure of a command looks like this:

/// Commands are stored as linked lists
typedef struct cmd_s {
    char  *nameP;        // command name - string to match
    void (*fnP)();       // function to execute if string matched
    struct cmd_s *nextP; // link to next command in this list
} Command;

The command interpreter code then has only a few EBMonitor-specific portions like those below (and most of those are just for efficiency):

void command_init(void) {
    // UART1 is normally used for console I/O, but
    // EBLink GDB Server supports console I/O via STLink debug interface
    // so we don't have to use the UART for debugging.  printf output
    // is buffered until \r\n or fflush(stdout) and then displayed in EB monitor
    // input is read from stdin (scanf, fgets, etc.)
    void    EBmonitor_buffer(FILE* , char*, uint16_t);
    #define EBM_outLength 128       // EB Monitor is used for debugging
    #define EBM_inLength 64
    static char EBM_out[EBM_outLength];
    static char EBM_in[EBM_inLength];

    // Route console I/O over the STLink debug interface
    EBmonitor_buffer(stdout, EBM_out, EBM_outLength);
    EBmonitor_buffer(stdin,  EBM_in,  EBM_inLength);
    // Turn off buffers, so I/O occurs immediately
    setvbuf(stdin, NULL, _IONBF, 0);
    setvbuf(stdout, NULL, _IONBF, 0);
    setvbuf(stderr, NULL, _IONBF, 0);

The rest of the command interpreter is the same between UART and STLinkV2 interfaces. For example:

/// Top-level command list
Command *commandsP;

/// Flag indicating a command is ready to be processed
unsigned char cmd_ready;

/// Buffer for current command being entered
#define MAX_CMD_LEN 80
static char cmd[MAX_CMD_LEN];

/// Prompt user for a command
void command_prompt(void) {

/// @returns true if a command is ready for processing
int command_ready(void)
    return !!cmd_ready;

/// Add a command to the head of the commands list
void command_add(Command **listP, Command *cmdP) {
    if (cmdP && listP) {
        cmdP->nextP = *listP;
        *listP = cmdP;

/// Display commands available in the specified command list
void list_commands(Command *listP) {
    printf("Commands: ");
    while (listP) {
       printf("%s ", listP->nameP);
       listP = listP->nextP;

// Call regularly from your main loop
void command_process(void)
    static int len;   // length of current command in buffer
    int ch = getchar();
    if (ch != EOF) {
        // drop received characters while waiting to process last command
        if (cmd_ready) return;

        if ((ch == '\r') || (ch== '\n')) {
            if (len) {
                cmd[len] = 0; // null terminate current command
                cmd_ready = 1;
                len      = 0;
            } else {
        } else if (ch == '\b') {
            if (len) {
                putchar(' ');
            } else {
                putchar('\a'); // sound beep
        } else if ((len+1 < MAX_CMD_LEN)) {
            cmd[len++] = ch;
        } else {
            putchar('\a'); // sound beep

    if (cmd_ready) {
        char *command = strtok(cmd, " \r\n");  // extract first command token
        command_execute(commandsP, command);
        cmd_ready = 0;


/// Search list of commands for specified command and execute if found
void command_execute(Command *listP, char *command) {
    // search list of commands and execute matching command if found
    Command *cmdP = listP;
    while (command && cmdP) {
        if (strcmp(command, cmdP->nameP) == 0) {
            // command found so execute associated function
        cmdP = cmdP->nextP;
    // command not found, show user the command options

    cmd_ready = 0;

Here’s an example of a command:

void fwinfo_fn(void) {
    printf("Built: %s\r\n",__DATE__ " " __TIME__);
static Command fwinfo_cmd = {"fwinfo", fwinfo_fn, 0};


command_add(&commandsP, &fwinfo_cmd);

Call command_process() from your main loop and voila…CLI!

EmBitz EBmonitor

When developing for embedded platforms, one of the first things I usually implement is a command-line-interface (CLI) which is invaluable for debugging. Traditionally, I use a UART, but when developing for STM32 targets using my favorite IDE (EmBitz), there’s another option that uses only the STLinkV2 debug probe and so doesn’t consume a UART (or require additional connections to the target). This option is EB monitor which uses the EMBitz GDB server replacement EBlink and works very well.

The documentation for EBmonitor is a bit thin, so here’s an example of how it is used:

#include <stdio.h>

// EBLink GDB Server supports console I/O via STLink debug interface
// so we don't have to use the UART for debugging.  printf output
// is buffered until \r\n or fflush(stdout) and then displayed in EB monitor
// input is read from stdin (scanf, fgets, etc.)
void    EBmonitor_buffer(FILE* , char*, uint16_t);
#define EBM_outLength 128       // EB Monitor is used for debugging
#define EBM_inLength 80
char    EBM_out[EBM_outLength];
char    EBM_in[EBM_inLength];

void cli_init() {
    // Route console I/O over the STLink debug interface
    EBmonitor_buffer(stdout, EBM_out, EBM_outLength);
    EBmonitor_buffer(stdin,  EBM_in,  EBM_inLength);

void sample_fn_using_cli() {
    fflush(stdout); // don't wait for EOL, send prompt now

    char in_buf[80];
    if (fgets(in_buf, sizeof(in_buf), stdin) {
        // process the user input
        char *token = strtok(NULL, " \r\n");
        // process token(s)

You can use all the standard format specifiers for printf: %u %s %lu…
You can use scanf, fgets, or any of the standard file/stream IO functions
Pretty sweet.

Your EmBitz project will have to be configured to use EBmonitor including:

  • Project->Build Options->Linker Settings->Categories: Debug features->Use EB monitor plugin
  • Debug->Plugins->EB monitor->Enable EB monitor
  • Debug->Plugins->EB monitor->Send NEWLINE as EOL on enter

STLinkV2 clone dongles are dirt cheap and beautifully integrated with EmBitz. You just Build and then start debugging. EmBitz uses the STLink to flash the target very fast and then lets you run in a full source-level debugger where you can set breakpoints, stop the processor, step through code, examine variables and memory. Using the same interface for your CLI means you only need the dongle and 4 wires connected to the target (includes power and ground!) to do development.