Skip to main content

Troubleshooting and FAQ

Applies to: C0-microSD primarily; the general block-device items apply to all SD-interface modules.

Work top to bottom: most bring-up problems are one of the first three items.

The device does not show up​

  1. Confirm you are looking for the right thing: an unformatted block device of the module's size (the C0-microSD is ~20.2 MB / 19.3 MiB). It never mounts as a filesystem. See Identify your module.
  2. Reseat the module and try a different reader or slot. Some readers do not handle SD 1.x cards; tested readers and hosts are listed in the host-compatibility table.
  3. On the SD-Dev, check that you power the board through the correct port for your configuration; see the SD-Dev page.

The OS asks me to format the device​

Dismiss the prompt. The module is intentionally unformatted; formatting writes over the on-device data layout.

I formatted the device by accident​

The Bootloader and Signaloid SoC bitstream regions are locked by default, so a format does not remove the module's core function. Re-flash your application (and any user data) with the toolkit; see Getting Started. If the device no longer responds at all, restore it with an external programmer; see Use External Programmer.

Permission denied on the device path​

Raw block-device access requires root privileges. Run the toolkit and host applications with sudo (administrator privileges on Windows).

The toolkit will not start​

A toolkit that exits immediately with a SyntaxError, a TypeError about unsupported operand types, or a message naming an unexpected argument is almost always running on a Python that is too old. The tools need Python 3.10 or later.

Check which interpreter your shell actually runs.

python3 -c 'import sys; print(sys.version_info >= (3, 10), sys.executable)'

If that prints False, install a newer Python. See Python Environment.

The version check passes but the tool still fails under sudo​

On Linux, sudo replaces your PATH, so sudo python3 can run a different interpreter from the one your shell uses. A newer Python that you installed for yourself is invisible to sudo unless you name it by its full path. Compare the two.

python3 -c 'import sys; print(sys.version_info >= (3, 10), sys.executable)'
sudo python3 -c 'import sys; print(sys.version_info >= (3, 10), sys.executable)'

When the second command reports an older interpreter, give sudo the full path to the one you installed, for example sudo /usr/bin/python3.12 C0_microSD_toolkit.py -t /dev/sdb -i. See Python Environment.

What the LEDs mean (C0-microSD)​

LED behaviorMeaning
Red solidBootloader mode
Green solidSignaloid SoC mode, application running
Green blinking rapidlyFlash operation in progress; do not remove power
Red or green blinkingSWITCHING state: the blinking LED shows the next boot mode; power-cycle to apply
No LED activity, no host connectedCustom user bitstream loaded; LED behavior is defined by the bitstream

See Modes and Custom Bitstream for the mode model. For the switching procedure, see Switch Between Operation Modes.

Flashing fails​

  • The device must be in Bootloader mode (solid red LED) to flash.
  • Pass the whole device to the toolkit (/dev/sdb, /dev/disk4), never a partition path such as /dev/sdb1.
  • Flash application binaries into the user data region, with the -u or -U toolkit option or the demo make flash target. See Getting Started.
  • MicroSD-to-SD adapters often have a write-protect switch on the side; if it is in the locked position, flashing fails with a permission error. See Flash the C0-microSD.

My application does not run​

  • Switch to Signaloid SoC mode and power-cycle after flashing; the change only takes effect on power-up.
  • The C0-microSD SoC copies the first 128 KiB of the user-data region into memory and executes from address 0x00. Check that your binary fits and was linked for that layout; see Programming and Toolchain.

The host application cannot communicate with the module​

  • The module must be in Signaloid SoC mode (solid green LED).
  • Open the block device so that polling reads bypass the host page cache, using O_DIRECT on Linux and the raw /dev/rdiskN node on macOS, because a buffered descriptor can keep returning a stale status value. The Python host interface handles this for you.
  • Check the host-side block offsets against the host offset map; they differ from the SoC-side addresses.

Frequently asked questions​

Can I use the module as regular storage? No. The exposed block device is the module's MMIO window (plus the flash regions in Bootloader mode), not general-purpose storage.

Do I need drivers? No. Any operating system that supports the standard SD protocol sees the module as a block device. See Host OS support.

Can I hot-swap the module? Yes, in normal operation. Do not remove power while a flash operation is in progress.

Does flashing wear anything out? The module stores applications and data in the on-board SPI flash, which supports at least 100,000 erase cycles per sector. Ordinary development flashing stays far below that. See Write and Erase Semantics.

I wrote data in Bootloader mode and nothing changed. The module writes its flash in whole 4 KiB sectors, and it discards a transfer that ends before the last byte of a sector without reporting an error. Write complete, 4 KiB-aligned sectors from the first byte to the last. This affects hosts that use SD over SPI, which transfer 512 bytes at a time. See Write and Erase Semantics.

My application loses its state after sitting idle. Some SD host controllers cut power to a card that has been idle and power it back up on the next transaction. The module restarts your device application on its own, so it keeps answering the host, but the application begins again from the start and keeps nothing that it held in memory. Read from the module at least once per second to keep the host controller from cutting power. See Power Cycles and State.

Where do I get help? Email developer-support@signaloid.com or open an issue on the relevant repository under the Signaloid GitHub organization.

Next steps​

Last updated on