USB

Overview

USB device is available on the Cores with a USB peripheral — Core.ST.L4 and Core.ST.H5. It runs crystal-less: the HSI48 oscillator plus the Clock Recovery System (synced to USB SOF) keeps the clock USB-accurate, so no external part is needed.

CDC serial

core_init() already starts USB on these Cores, so core_usb_init() is a harmless no-op you can keep for clarity. Then write like any serial port. Writes queue and return at once; with a terminal that stops reading they wait at most 50 ms, then drop. core_usb_connected() tells you the host has actually opened the port:

#include "core.h"
  #include "core_usb.h"        // Core.ST.L4 / H5; core.h includes it when "usb" is enabled
  #include "core_watchdog.h"

  core_usb_init();

  while (1) {
      core_watchdog_feed();
      if (core_usb_connected()) {
          core_usb_printf("adc=%u ticks=%lu\r\n", raw, core_millis());
      }
      core_delay_ms(500);
  }

Text printed before a terminal opens the port isn’t lost: it waits in the TX queue (up to its size) and goes out when the port opens. To wait for a terminal at start-up, core_usb_wait_host(ms) returns 1 once one is connected, or 0 on timeout, feeding the watchdog while it waits.

Receiving

Two RX modes. Poll a background ring buffer, or register a callback that fires from the USB interrupt as bytes arrive (when set, data isn’t buffered for polling):

// Polling:
  while (core_usb_available()) {
      uint8_t b = core_usb_getc();
  }

  // Or callback-driven:
  static void on_rx(const uint8_t *data, uint16_t len, void *ctx) { /* ... */ }
  core_usb_on_receive(on_rx, NULL);

For text commands, the line assembler collects bytes into lines. core_usb_poll_line() reads from the ring buffer (so not with a receive callback) and returns a finished line, without its ending, or NULL. Lines end at \n (\r\n works too), up to 127 characters:

#include <string.h>

  static core_usb_line_t lr;            // zero-initialized

  // in the loop:
  const char *line = core_usb_poll_line(&lr);
  if (line && strcmp(line, "led on") == 0) core_led_on();

core_usb_line_feed() does the same one byte at a time, for bytes you already have (from a callback, say). In Studio, on Core.USB.line(text) delivers each line.

HID reports

Alongside CDC, the device exposes a vendor HID interface for raw 64-byte reports — handy for a custom host tool (via hidapi / pyusb / Web HID) with no OS driver. Reports go both ways:

#include "core_usb_hid.h"

  uint8_t report[8] = { 0x01, 0x02, 0x03, 0x04 };
  core_usb_hid_send(report, sizeof(report));   // zero-padded to 64 bytes

  // host -> device: one report per call, from the USB interrupt
  static void on_report(const uint8_t *data, uint16_t len, void *ctx) { /* ... */ }
  core_usb_hid_set_rx_callback(on_report, NULL);

Cross-architecture support

CDC serial is the verified path on the USB-capable Cores; HID rides the same stack. MSC and USB host are not implemented. (The ROM DFU bootloader is covered in bootloading.)

See the implementation status for the full matrix.

Known gaps

What the SDK itself lists as missing here, straight from the headers:

API reference

void core_usb_print(const char * s);

void core_usb_print_int(int v);

void core_usb_print_float(double v);

void core_usb_print_bool(int v);

void core_usb_init(void);

int core_usb_connected(void);

int core_usb_wait_host(uint32_t timeout_ms);

int core_usb_write(const uint8_t * buf, uint16_t len);

int core_usb_try_write(const uint8_t * buf, uint16_t len);

void core_usb_on_receive(hal_usb_cdc_rx_cb_t cb, void * ctx);

uint16_t core_usb_available(void);

uint8_t core_usb_getc(void);

uint16_t core_usb_read(uint8_t * buf, uint16_t max);

int core_usb_try_read(uint8_t * byte);

char * core_usb_line_feed(core_usb_line_t * lr, uint8_t byte);

char * core_usb_poll_line(core_usb_line_t * lr);

int core_usb_hid_send(const uint8_t * buf, uint16_t len);

void core_usb_hid_set_rx_callback(hal_usb_hid_rx_cb_t cb, void * ctx);