MeshTerm/docs/devices/cardputer-zero.md

MeshTerm on the Cardputer Zero

M5Stack makes three Cardputers. This page is about the Cardputer Zero. It has a Raspberry Pi Compute Module 0 inside, and it runs Linux. The original Cardputer and the Cardputer-Adv are ESP32 microcontroller boards. They cannot run MeshTerm, and nothing on this page applies to them.

MeshTerm is an app in M5Stack's app store for the Cardputer Zero. It starts from the launcher of the handheld and draws on its display. It can drive M5Stack's Cap LoRa-1262 radio directly, or it can use a MeshCore companion. MeshTerm supports both models of the handheld: the Cardputer Zero and the Cardputer Zero Lite.

• The device
• What works
• Installing it on the device
• Trying it in the emulator
• Radios

---

The device

Models	Cardputer Zero (C154) and Cardputer Zero Lite (C155). MeshTerm supports both
Computer	Raspberry Pi Compute Module 0: four 1 GHz cores, 512 MB of memory
Screen	1.9 inches, 320×170 pixels
Keyboard	46 keys, with Shift, Fn and Sym layers
System	Raspberry Pi OS "Trixie", with M5Stack's own app launcher

The two models have the same computer, display, keyboard, battery, and expansion header. The Cardputer Zero also has a camera, motion sensors, and a 32 GB microSD card. MeshTerm uses none of these three parts, thus it works in the same way on both models. The Lite comes without a microSD card. It needs a card with M5Stack's system on it before it can start (refer to M5Stack's documentation).

MeshTerm draws the display in 53 columns by 14 rows. The width is the same as on the PicoCalc, but the height is approximately half. Thus many screens have a more compact layout here.

The launcher gives an app the whole display and the keyboard, but it gives no text console to run in. Thus MeshTerm has its own console. This is a small program inside MeshTerm. It draws each character on the display itself and reads the keys directly.

What works

All of these were tried on a real Cardputer Zero:

• MeshTerm starts from M5Stack's app launcher and draws on the display itself.
• MeshTerm has a layout for the display of 14 rows. The title bar also shows the unread count and the battery. The tab strips have one row. The dialogs fit the short display.
• The battery in the title bar is the Cardputer Zero's own battery.
• The row of function-key labels is along the bottom of the display. Fn+4 to Fn+8 drive it. These keys are directly under the display. Shift with them gives a second set.
• M5Stack's Cap LoRa-1262 radio add-on (refer to Radios).
• Hold Esc to quit. This is how the launcher closes each app. After one second, MeshTerm shows a box that says so. The box has a bar that fills over the next two seconds. While the box is visible, MeshTerm sends nothing new over the radio. If you release Esc before the bar is full, you return to the screen that you were on. If you keep holding it, MeshTerm saves everything and closes in good time, before the launcher forces it. A short press of Esc still goes back one screen, as on all other handhelds.

Installing it on the device

From the app store

1. On the Cardputer Zero, open M5Stack's app store.
2. Find MeshTerm. It is in the Radio & Comms category. Its share code is MTRM.
3. Install it.

MeshTerm now has an icon in the launcher. The package has all that MeshTerm needs: its Python libraries, the radio library for the Cap, and the font of the display. Each new version of MeshTerm also goes to the store.

The store gets a new version a short time after its release, when the check of the store passes. If you want a new version before the store has it, install the same package from GitHub.

From GitHub

Each release of MeshTerm has the package that the store has, meshterm_<version>-1_arm64.deb. Copy it to the Cardputer Zero, for example with scp. Then install it from a command line on the handheld:

sudo apt install ./meshterm_*_arm64.deb

To remove it, run sudo apt remove meshterm.

From the source code

This way is for developers who know a Linux command line. The Cardputer Zero must be on Wi-Fi. You also need a way to type commands on it. SSH from another computer is the easiest way.

1. Get MeshTerm and the radio library, and download the font that the display uses:

git clone https://github.com/jpmartineau/MeshTerm.git
cd MeshTerm
python3 -m venv .venv
.venv/bin/pip install -e '.[spi]'
.venv/bin/meshterm emulate --fetch-fonts

2. Put MeshTerm in the launcher. The command asks for your password one time, because the list of apps of the launcher belongs to the system:

scripts/cardputer-zero/launcher-entry.sh

MeshTerm now has an icon in the launcher. The icon is a negative of the MeshTerm logo. Thus it is different from the icon of MeshTerm from the app store, and you can have both. To remove the icon, run scripts/cardputer-zero/launcher-entry.sh remove.

Typing long text from your computer

A long password or key is hard to type on a keyboard this small. Use another computer that can reach the Cardputer over SSH. The tool scripts/cardputer-zero/type-text.py types the text for you, into the app that has the display:

python scripts/cardputer-zero/type-text.py --host pi@cardputer.local

1. On the Cardputer, open the field that you want to fill.
2. Run the command above on your computer.
3. Paste the text when the tool asks for it, and press Enter. The tool does not show your typing. The text goes to the Cardputer over SSH, thus it does not show on either display.
4. Do not touch the Cardputer's keyboard until the tool says that it is done.

Trying it in the emulator

The emulator opens a window that shows the display of the Cardputer Zero. The window scales the display up so that you can read it. If you run it with a simulated radio, you can try the layout without the handheld and without a radio.

The emulator is not a strict emulator. It does not copy the computer of the Cardputer Zero. MeshTerm runs on your own computer, at the speed of your computer. The emulator copies the constraints of the display and the keyboard: the size of the display in pixels, the font, the colours, and the keys that drive the labels along the bottom. This shows what fits on the display and what does not. That is the purpose of the emulator.

The emulator needs MeshTerm installed with pip or pipx (refer to the README). The one-file downloads do not have the part of Python that opens windows.

1. Download the font that the display uses. Do this one time:

meshterm emulate --fetch-fonts

2. Start the emulator:

meshterm emulate cardputer-zero --mock

--mock is the simulated radio. Before you start, set MESHTERM_HOME to an empty folder. Then the made-up nodes of the simulation stay out of your real history. --scale 4 makes the window bigger.

In the window, the F4 to F8 keys of your keyboard replace Fn+4 to Fn+8. Hold Shift to show the second set. You can also click the keys. Click the keys that are drawn under the display, or the coloured keys along its bottom row. Hold Shift while you click for the second set. Ctrl+Shift+S saves a screenshot at the real size of the display. When you close the window, MeshTerm quits. It also quits when you hold Esc for three seconds, as it does on the handheld.

Radios

The Cardputer Zero has no LoRa radio built in. You can add one in three ways:

Radio	Status
Cap LoRa-1262 add-on board from M5Stack	Works, with no setup. MeshTerm runs the mesh node itself while it is open, as it does on a uConsole.
A MeshCore companion on USB	Expected to work as on any Linux computer.
A MeshCore companion over Bluetooth	Expected to work as on any Linux computer.

The Cap LoRa-1262

CAUTION: Turn off the Cardputer Zero before you install or remove a Cap, also the Cap LoRa-1262. M5Stack does not support hot swapping of a Cap on the Cardputer Zero. In M5Stack's words, "hot-swapping may cause the device to malfunction" (refer to M5Stack's documentation).

CAUTION: Install the antenna on the Cap before you turn on the Cardputer Zero. M5Stack says that power without the antenna can permanently damage the radio.

1. Turn off the Cardputer Zero.
2. Install the antenna on the Cap.
3. Push the Cap onto the expansion header at the back.
4. Turn on the Cardputer Zero, and start MeshTerm.

The device screen lists the Cap as Cap LoRa-1262. meshterm --spi also reaches it from the command line.

The Cap has no MeshCore firmware of its own. It is only a radio chip. Thus, while MeshTerm is open, MeshTerm is the node, as it is on the AIO board of a uConsole. MeshTerm needs the radio library. The package from the store has it. If you install MeshTerm with pip, install the library next to it:

pip install 'mesh-term[spi] @ git+https://github.com/jpmartineau/MeshTerm'

When MeshTerm connects, it does three things that the Cardputer Zero needs before the radio answers:

• It switches on the power to the expansion header. The power is off until a program asks for it.
• It makes sure that two pins of the header connect to the radio and not to the USB port that shares them.
• It switches on the antenna path of the Cap.

When MeshTerm quits, it switches the power of the header off. Thus the Cap does not drain the battery while nothing uses it. But this does not make it safe to remove the Cap. Turn off the Cardputer Zero first.

A new node starts with the US/Canada settings of MeshCore (910.525 MHz). In other regions, change the settings on Device config before you send anything. MeshTerm keeps the key, the contacts, and the channels of the node in ~/.meshterm/radio/spidev0.1/.

The Cap's GPS

The Cap also has a GPS. MeshTerm can use it to keep the position of your node current. The GPS is off until you switch it on, as on MeshCore firmware. To switch it on:

1. Open Device config.
2. Under Custom variables, set GPS to on.
3. Apply.

When the GPS has a fix, the fix becomes the position of your node. In the open air, the first fix usually takes approximately one minute. Indoors, the fix may never come.

Two things do not change:

• You decide if your adverts include your position. This is the Share location setting on Device config. If it is off, the GPS still moves your node on MeshTerm's own map, but nobody else sees where you are.
• A hand move of your node on the map does not stay while the GPS is on. The next fix puts the node back where the GPS says you are. Switch the GPS off first.

GPS interval sets how often the position changes, in seconds. The default is 0. This means each fix, approximately one each second. MeshTerm remembers your last fix when it quits. Thus the next start begins where you were.

The GPS talks to the Cardputer over a serial port, as a companion on a USB cable does. But it is not a companion, thus the device screen does not list it.