--- title: Using a Serial Terminal with Notecard description: Configure CoolTerm, Tera Term, PuTTY, and other serial terminal apps on macOS, Windows, and Linux to send Notecard API requests over USB or AUX serial. source_url: https://dev.blues.io/guides-and-tutorials/notecard-guides/using-a-serial-terminal-with-notecard/ canonical_url: https://dev.blues.io/guides-and-tutorials/notecard-guides/using-a-serial-terminal-with-notecard/ markdown_url: https://dev.blues.io/guides-and-tutorials/notecard-guides/using-a-serial-terminal-with-notecard.md --- # Using a Serial Terminal with Notecard Every Notecard interface speaks the same protocol: newline-delimited JSON requests in, newline-delimited JSON responses out. That means any serial terminal application can act as a development and debugging tool for Notecard with no firmware, host MCU, or library required. You type a [Notecard API request](https://dev.blues.io/api-reference/notecard-api.md), press `Enter`, and read the response. There are three ways to talk to a Notecard from your computer: - The [In-Browser Terminal](https://dev.blues.io/terminal/), which needs no installation but requires a browser that supports the Web Serial API. - The [Notecard CLI](https://dev.blues.io/tools-and-sdks/notecard-cli.md), a command-line utility. - A serial terminal application, which is what this guide covers. > **Tip:** > > If you're just getting started, try the [In-Browser Terminal](https://dev.blues.io/terminal/) first as it requires no setup at all. Try a serial terminal app when you need to capture a long-running log to a file, when your Notecard is connected over `AUX` `RX`/`TX` rather than USB, or when you're using a browser without Web Serial support (e.g. Safari). ## Table of Contents 1. [Choosing a Terminal App](#choosing-a-terminal-app) 2. [Baseline Serial Port Settings](#baseline-serial-port-settings) 3. [Setting Up CoolTerm](#setting-up-coolterm) 4. [Setting Up Tera Term](#setting-up-tera-term) 5. [Using Other Terminal Apps](#using-other-terminal-apps) 6. [Capturing a Log](#capturing-a-log) ## Choosing a Terminal App Any serial terminal application that can send a line of text and display the response will work with Notecard. The table below lists the applications most commonly used by Blues customers, and the platforms each one supports. | Application | macOS | Windows | Linux | | ----------------------------------------------------------------------- | ----- | ------- | ----- | | [CoolTerm](https://freeware.the-meiers.org/) | ✅ | ✅ | ✅ | | [Tera Term](https://teratermproject.github.io/index-en.html) | — | ✅ | — | | [PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html) | — | ✅ | ✅ | | `screen` | ✅ | — | ✅ | | [minicom](https://salsa.debian.org/minicom-team/minicom) | — | — | ✅ | | [GTKTerm](https://github.com/wvdakker/gtkterm) | — | — | ✅ | | [Arduino Serial Monitor](https://www.arduino.cc/en/software) | ✅ | ✅ | ✅ | This guide walks through [CoolTerm](#setting-up-coolterm) and [Tera Term](#setting-up-tera-term) in detail, and provides the essential settings for [the rest](#using-other-terminal-apps). If you have no existing preference, CoolTerm is a good default: it runs on all three platforms, so the same instructions apply to your whole team. > **Note:** > > No driver installation is required to communicate with a Notecard over USB. The USB interface appears to your computer as a standard USB 2.0 Full Speed CDC device, which Linux, Windows, and macOS all support natively. ## Baseline Serial Port Settings Before configuring your terminal application, you need to know two things: which serial port your Notecard is attached to, and which settings that port expects. ### Identifying the Serial Port Connect your Notecard to your computer, then locate the port it enumerated as. - **macOS** — run `ls /dev/tty.usbmodem*` in a terminal. Notecard typically enumerates as something like `/dev/tty.usbmodem14201`. - **Linux** — run `ls /dev/ttyACM*`. Notecard typically enumerates as `/dev/ttyACM0`. If you get a permissions error when connecting, add your user to the `dialout` group with `sudo usermod -a -G dialout $USER`, then log out and back in. - **Windows** — open Device Manager and expand **Ports (COM & LPT)**. Look for a `USB Serial Device` entry and note its COM number, for example `COM3`. > **Tip:** > > If more than one port appears and it isn't obvious which is the Notecard, list the ports with the Notecard unplugged, plug it in, and list them again. The port that appears the second time is the one you want. ### Port Configuration The settings depend on which Notecard interface you've connected to. | Connection | Baud Rate | Data Bits | Parity | Stop Bits | Flow Control | | ----------------- | ---------------------------- | --------- | ------ | --------- | ------------ | | USB | Any (9600 is a safe default) | 8 | None | 1 | None | | `N_RX`/`N_TX` | 9600 | 8 | None | 1 | None | | `AUX RX`/`AUX TX` | 115200 (default) | 8 | None | 1 | None | > **Note:** > > Because the USB interface is a CDC device, the baud rate you select is ignored — any value will connect successfully. The `N_RX`/`N_TX` interface is fixed at 9600 and will produce garbled output at any other rate. > > `115200` is the AUX **default**, not a fixed rate. A [`card.aux.serial`](https://dev.blues.io/api-reference/notecard-api/card-requests.md#card-aux-serial) request can change it with the `rate` argument, and AUX GPS mode (`"mode":"gps"`) defaults to `9600` instead. If AUX output is garbled, confirm the rate the Notecard is actually using before assuming 115200. > > Also, the `AUX RX`/`AUX TX` interface is only enabled when `AUX_EN_P` (pin 56) is pulled up to `VIO`. On a Notecarrier, bridge the `AUXEN` header to ` New connection**. 2. Choose the **Serial** radio button, and select the COM port your Notecard is attached to from the **Port** dropdown. 3. Click **OK**. ![Tera Term New connection dialog with the Serial option selected and a COM port chosen](https://dev.blues.io/images/guides/notecard-guides/serial-terminal/teraterm-new-connection.png?v=5b4e009d) ### Configure the Serial Port 1. Select **Setup > Serial port**. 2. Apply the following settings: | Setting | Value | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Speed | `9600` for USB or `N_RX`/`N_TX`, `115200` for `AUX RX`/`AUX TX` (see [Baseline Serial Port Settings](#baseline-serial-port-settings) if the AUX rate has been changed) | | Data | `8 bit` | | Parity | `none` | | Stop bits | `1 bit` | | Flow control | `none` | 3. Click **Ok** to apply. ![Tera Term Serial port setup dialog showing the speed, data, parity, stop bits, and flow control settings](https://dev.blues.io/images/guides/notecard-guides/serial-terminal/teraterm-serial-port.png?v=00154ac3) ### Configure the Terminal 1. Select **Setup > Terminal**. 2. Set **New-line Receive** to `CR+LF` and **New-line Transmit** to `CR+LF`. 3. Check **Local echo**. 4. Click **OK**. ![Tera Term Terminal setup dialog showing CR+LF new-line receive and transmit with Local echo checked](https://dev.blues.io/images/guides/notecard-guides/serial-terminal/teraterm-terminal.png?v=cd6f3bad) ### Send a Request Type a [Notecard API request](https://dev.blues.io/api-reference/notecard-api.md) directly into the terminal window and press Enter. ```json {"req":"card.version"} ``` ```json { "version": "notecard-11.3.1.17696", "device": "dev:351077454518609", "name": "Blues Wireless Notecard", "sku": "NOTE-WBGLW", "ordering_code": "HB0YT1N0AEAU", "board": "5.13", "wifi": true, "cell": true, "gps": true, "body": { "org": "Blues Wireless", "product": "Notecard", "target": "u5", "version": "notecard-u5-11.3.1", "ver_major": 11, "ver_minor": 3, "ver_patch": 1, "ver_build": 17696, "built": "Jun 11 2026 16:25:45" } } ``` ![Tera Term connected to a Notecard, showing a card.version request and its JSON response](https://dev.blues.io/images/guides/notecard-guides/serial-terminal/teraterm-request.png?v=d31549c0) > **Tip:** > > Tera Term transmits each keystroke as you type it, so you cannot edit a request once you've started typing. If you prefer to compose requests before sending them, paste them in from a text editor, or use [CoolTerm](#setting-up-coolterm) in Line Mode instead. ## Using Other Terminal Apps CoolTerm and Tera Term are the applications Blues documents most thoroughly, but any serial terminal will work. Apply the settings from [Baseline Serial Port Settings](#baseline-serial-port-settings) to the application of your choice. ### PuTTY (Windows, Linux) In the PuTTY configuration window, select the **Serial** connection type, enter your port in **Serial line** (for example `COM3` or `/dev/ttyACM0`), and enter your baud rate in **Speed**. Then open the **Connection > Serial** category and confirm `8` data bits, `1` stop bit, `None` parity, and `None` flow control. Under **Terminal**, enable **Implicit CR in every LF** and **Local echo** so that responses render on separate lines and your typed requests are visible. ### screen (macOS, Linux) `screen` is preinstalled on macOS and most Linux distributions, and connects with a single command: ```bash screen /dev/tty.usbmodem14201 9600 ``` Substitute your own port and baud rate. To exit, press `Ctrl-A` followed by `K`, then confirm with `y`. > **Note:** > > `screen` does not echo what you type and offers no line editing, so a typo means retyping the request from the beginning. It's convenient for a quick `card.version` check, but [CoolTerm](#setting-up-coolterm) or `minicom` is a better choice for extended debugging sessions. ### minicom (Linux) Install `minicom` from your distribution's package manager, then launch it with the port and baud rate: ```bash minicom --device /dev/ttyACM0 --baudrate 9600 ``` Press `Ctrl-A` then `Z` for the help menu, and `Ctrl-A` then `E` to turn on local echo. To exit, press `Ctrl-A` then `X`. ### Arduino Serial Monitor (macOS, Windows, Linux) If you already have the [Arduino IDE](https://www.arduino.cc/en/software) installed, its Serial Monitor works well with Notecard. Select your port from **Tools > Port**, open **Tools > Serial Monitor**, then set the line ending dropdown to **Both NL & CR** and the baud rate dropdown to match your connection. ## Capturing a Log When you're debugging a connectivity problem — or working with Blues support or the [community forum](https://discuss.blues.com) — it's helpful to capture the terminal session to a file rather than copying text out of the scrollback. This is especially true when using [trace mode](https://dev.blues.io/support/using-notecard-trace-mode.md), which emits a continuous stream of messages that can quickly exceed your terminal's buffer. ### Capturing in CoolTerm 1. Select **Connection > File Capture > Start**. 2. Give the file a name and click **Save**. 3. Reproduce the behavior you want to capture. 4. Select **Connection > File Capture > Stop** when you're finished. ### Capturing in Tera Term 1. Select **File > Log**. 2. Check **Append** and **Plain text**. 3. Give the file a name and click **Save**. 4. Reproduce the behavior you want to capture. Tera Term writes to the log file continuously until you select **File > Stop logging**. ### Capturing Trace Output To capture the most useful debugging information, start your log file first, then enable trace mode: ```json {"req":"card.trace","mode":"on"} ``` Perform the actions you want to debug — for example a `hub.sync` request — then disable trace mode and stop the capture: ```json {"req":"card.trace","mode":"off"} ``` > **Warning:** > > Trace output is emitted only over the USB serial port or Notecard's `AUX RX`/`AUX TX` serial port. It is not sent over `I2C`, and it is not sent over the primary `N_RX`/`N_TX` serial pins that a host normally uses. See [Using Notecard Trace Mode](https://dev.blues.io/support/using-notecard-trace-mode.md) for more. ## Additional Resources - [Notecard API](https://dev.blues.io/api-reference/notecard-api.md) - [Notecard Interfaces](https://dev.blues.io/notecard/notecard-walkthrough/notecard-interfaces.md) - [Using Notecard Trace Mode](https://dev.blues.io/support/using-notecard-trace-mode.md) - [Debugging a Notecard with the FTDI Debug Cable](https://dev.blues.io/guides-and-tutorials/notecard-guides/debugging-with-the-ftdi-debug-cable.md) - [Notecard Error and Status Codes](https://dev.blues.io/support/notecard-error-and-status-codes.md)