Signal Utilities

Cuttlefish gives you a handful of helpers for the things that sit between “read a pin” and “talk to another chip”: playing a tone (a square wave — the beep from a buzzer), measuring pulses, shifting bits in and out, and making random numbers.

Tone Generation

The Tone API plays a tone (a square wave — the beep from a buzzer) at a specific frequency on any digital pin. It is primarily used for driving buzzers, speakers, or generating audio-based status signals.

Basic Usage

Start a continuous tone or a timed beep using the fluent .for() builder.

import { D8 } from '@typecad/board';

const speaker = D8.asOutput();

// Play 440Hz (A4) indefinitely
speaker.tone(440);

// Stop the tone
speaker.noTone();

// Play a 1000Hz beep for 500ms
speaker.tone(1000).for(500);

Pulse Measurement

The Pulse utility measures the duration of a signal pulse (HIGH or LOW) in microseconds. This is critical for sensors like ultrasonic rangefinders or reading incoming PWM signals from RC receivers.

Fluent API

The fluent API provides a readable way to configure timeouts and pulse polarities.

import { Pulse, D7 } from '@typecad/board';

// Measure a HIGH pulse on D7
const duration = Pulse.on(D7).high();

// Measure a LOW pulse with a custom 20ms timeout
const echoTime = Pulse.on(D7).timeout(20000).low();

Long Pulses

For pulses too long for the standard timer (e.g. an ultrasonic sensor on a slow echo), Pulse.long uses high-precision 64-bit timers:

import { Pulse, D7 } from '@typecad/board';

// Measure a long HIGH pulse with the high-resolution timer
const echoMicros = Pulse.long(D7, 1);  // 1 = HIGH, 0 = LOW

Shift Registers (Bit-Banging)

Shift registers let you expand your I/O pins by sending data over two or three wires. The Shift utility does this with bit-banging (driving a protocol in software instead of with hardware) for both input and output expansion.

Shifting Out (Output Expansion)

Send 8 bits of data to an output shift register like the 74HC595. You can send MSB (most significant bit) first or LSB (least significant bit) first.

import { Shift, D2, D3 } from '@typecad/board';

const dataPin = D2.asOutput();
const clockPin = D3.asOutput();

// Send the value 0b10101010, Most Significant Bit first
Shift.out(dataPin, clockPin, 'msb', 0xAA);

// Fluent style
Shift.write(dataPin, 0xAA).clock(clockPin).msbFirst();

Shifting In (Input Expansion)

Read 8 bits of data from an input shift register like the 74HC165.

// Read 8 bits LSB (Least Significant Bit) first
const state = Shift.read(dataPin).clock(clockPin).lsbFirst();

Random Numbers

The Random utility provides access to the hardware’s PRNG (pseudo-random number generator).

Seeding

For better randomness, it is recommended to seed the generator with noise from an unconnected analog pin.

import { Random, A0 } from '@typecad/board';

const noise = A0.asInput();
Random.seed(noise.readAnalog());

Generating Values

// Generate a number from 0 to 99
const val = Random.upTo(100);

// Generate a number between 10 and 20
const range = Random.between(10, 20);

// Generate a full 32-bit random integer
const bigNum = Random.int();

API Reference

Tone Methods (on BasePin)

Pulse Utility (Pulse)

Shift Utility (Shift)

Random Utility (Random)