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.
Minicom installation on macOS requires the Homebrew package manager. Install it from its web site if you have not done so already.
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:
Open a terminal. The device file should be /dev/ttyACM0
. You may need to ensure you have access to the serial port: on most distributions this can be done by adding your user account to the dialout
user group.
Run minicom -o -D /dev/ttyACM0
Open a terminal. Enter ls /dev/cu*
. You should see an entry like: /dev/cu.usbserial-FTWHFLU9
. This is the FTDI device file.
Run minicom -o -D /dev/cu.usbserial-FTWHFLU9
Open Device Manager. It will show the cable as a USB Serial Device in the Ports (COM & LPT) section. Note its COM number and speed.
Run PuTTY, select Serial as the Connection type, and enter its COM number in the Serial line field. Make sure the Speed field is set to match the value you got from Device Manager.
Click Open.
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(×tamp[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.