Disconnected Device Debugging with Microvisor

Battery operated devices commonly disable wireless and cellular networks to save power. Mains-powered devices may be configured to continue operating even when connectivity has been lost due to circumstances beyond the device’s control. With no network connectivity, logging is a challenge.

In order to add visibility to the state of your product during periods of unexpected connectivity loss, you can employ one of the many digital communication protocols available to your device’s microcontroller, in particular UART. This standard bus is a great choice for its ease of use and wide availability.

By using a UART for offline debugging you can send the same messages you would via Microvisor’s mvServerLog() system call to a serial port with just a few simple hardware modifications. We’ll describe below how you can take advantage of this technique.

Tools

You’ll need a few extra tools in order to use UART for debugging. These tools comprise both software and hardware but are either low cost or free.

We recommend using a TTL UART-to-USB (COM port emulator) cable to view debug messages on your workstation. Connect this cable to pins (or test points) on the DUT.

You will also need terminal software and to modify the device code to output debug messages over serial. We have collected the information you need to source components and software.

FTDI cable

We recommend FTDI cables because they are highly available and relatively inexpensive. They are available with either a female 0.1-inch socket or bare wire termination, so select one on the basis of your application. They are available in 3.3V and 5V signal levels, and it is important that you always use the version that matches your microcontroller’s GPIO logic high voltage.

Drivers

You will need to install the FTDI drivers for your OS. Ubuntu 20.0.4 comes with FTDI drivers built in, as does macOS (10.9 and above). Windows users will need to install VCP (Virtual COM Port) drivers, which are available from FTDI.

Terminal software

There are many options available depending on your OS. Linux and macOS both come with Terminal utilities; these can be used to run a command-line utility called Minicom which lets you send and receive information via UART. Install Minicom using your OS’ package manager.

• Linux sudo apt install minicom
• macOS brew install minicom

Windows users should download Simon Tatham’s PuTTY, which combines the role of terminal and Minicom.

Setup

Hardware

To demonstrate UART connectivity, we’ll use the Microvisor Nucleo Development Board (NDB). Microvisor makes four full-power UART buses — USART1, USART2, USART3, and UART4 — available to the application. We will use USART2 in the code below, but you should choose your own bus based on your device’s pin availability.

USART2 connects through GPIO pins PA2 and PD5 (TX), and PA3 and PD6 (RX). For the sample code, we’ve chosen pins PD5 and PD6. In fact, we only need PD5, as we’ll configure the UART for TX only.

Connect your FTDI cable to one of your computer’s USB ports, and its RX wire (usually colored yellow) to PD5, which is pin 41 of block CN11 on the NDB. This is the GPIO header alongside the SIM card slot. Connect the FTDI’s GND wire to pin 49 of CN11.

Software

Be sure to set the serial terminal connection to use the FTDI cable and match the following settings:

• Baud Rate User choice, e.g., 115,200
• Data Bits/Word Length 8
• Parity None
• Stop Bits 1

On your computer:

Application code

The following sample can be used to add serial logging to your application. It leverages USART2 via pin PD5. The bus is set to TX only and an ‘8N1’ configuration. You can alter these choices by editing the functions UART_init() and HAL_UART_MspInit(). In fact, the code demonstrates how to set up a standard UART connection using the STM32U585 HAL library: configure the UART, set the appropriate clocks, and configure the GPIO pins supporting the bus.

In your project, create the files uart_logging.h and uart_logging.c, and add the following code to the latter:

#include "uart_logging.h"

UART_HandleTypeDef uart;

/**
 * @brief Configure STM32U585 UART1.
 */
void UART_init() {
  uart.Instance           = USART2;
  uart.Init.BaudRate      = 115200;              // Match your chosen speed
  uart.Init.WordLength    = UART_WORDLENGTH_8B;  // 8
  uart.Init.StopBits      = UART_STOPBITS_1;     // N
  uart.Init.Parity        = UART_PARITY_NONE;    // 1
  uart.Init.Mode          = UART_MODE_TX;        // TX only mode
  uart.Init.HwFlowCtl     = UART_HWCONTROL_NONE; // No CTS/RTS

  // Initialize the UART
  if (HAL_UART_Init(&uart) != HAL_OK) {
    // Log error
    return;
  }
}

/**
 * @brief HAL-called function to configure UART.
 *
 * @param uart: A HAL UART_HandleTypeDef pointer to the UART instance.
 */
void HAL_UART_MspInit(UART_HandleTypeDef *uart) {
  // This SDK-named function is called by HAL_UART_Init()

  // Configure U5 peripheral clock
  RCC_PeriphCLKInitTypeDef PeriphClkInit = { 0 };
  PeriphClkInit.PeriphClockSelection = RCC_PERIPHCLK_USART2;
  PeriphClkInit.Usart2ClockSelection = RCC_USART2CLKSOURCE_PCLK1;

  // Initialize U5 peripheral clock
  if (HAL_RCCEx_PeriphCLKConfig(&PeriphClkInit) != HAL_OK) {
    // Log error
    return;
  }

  // Enable the UART GPIO interface clock
  __HAL_RCC_GPIOD_CLK_ENABLE();

  // Configure the GPIO pins for UART
  // Pin PD5 - TX
  GPIO_InitTypeDef gpioConfig = { 0 };
  gpioConfig.Pin       = GPIO_PIN_5;               // TX pin
  gpioConfig.Mode      = GPIO_MODE_AF_PP;        // Pin's alt function with pull...
  gpioConfig.Pull      = GPIO_NOPULL;              // ...but don't apply a pull
  gpioConfig.Speed     = GPIO_SPEED_FREQ_HIGH;
  gpioConfig.Alternate = GPIO_AF7_USART2;        // Select the alt function 

  // Initialize the pins with the setup data
  HAL_GPIO_Init(GPIOD, &gpioConfig);

  // Enable the UART clock
  __HAL_RCC_USART2_CLK_ENABLE();
}

/**
 * @brief Issue any log message via serial logging.
 *
 * @param format_string Message string with optional formatting
 * @param ...           Arbitrary number of additional args
 */
void uartlog(char* format_string, ...) {
  char buffer[1024] = {0};
  va_list args;
  va_start(args, format_string);

  // Add a timestamp
  char timestamp[64] = {0};
  uint64_t usec = 0;
  time_t sec = 0;
  time_t msec = 0;
  enum MvStatus status = mvGetWallTime(&usec);
  if (status == MV_STATUS_OKAY) {
    // Get the second and millisecond times
    sec = (time_t)usec / 1000000;
    msec = (time_t)usec / 1000;
  }

  // Write time string as "2022-05-10 13:30:58.XXX "
  strftime(timestamp, 64, "%F %T.XXX ", gmtime(&sec));

  // Insert the millisecond time over the XXX
  sprintf(&timestamp[20], "%03u ", (unsigned)(msec % 1000));

  // Write the timestamp to the message
  strcpy(buffer, timestamp);
  size_t len = strlen(timestamp);

  // Write the formatted text to the message
  vsnprintf(&buffer[len], 1016, format_string, args);

  // Add RETURN and NEWLINE to the message and output to UART
  sprintf(&buffer[strlen(buffer)], "\r\n");
  HAL_UART_Transmit(&uart,
                    (const uint8_t*)buffer,
                    (uint16_t)strlen(buffer),
                    100);
  va_end(args);
}

Add a declaration for the first and last function to the header file:

void UART_init();
void uartlog(bool is_err, char* format_string, ...);

Make sure the files are included in your project’s build configuration, and that you call UART_init() from your main(). Build and deploy a new version of your application.

Now update your code to call uartlog() alongside mvServerLog(). The function takes a format string and zero or more arguments to be interpolated into it. The message passed into the call will be UTC-timestamped and issued using Microvisor application logging and over UART. If the device is connected, you can view both streams in parallel, or you can view solely the UART output if the device is disconnected.