CRSF JS

A lightweight, cross-environment TypeScript/JavaScript library for parsing and serializing CRSF (Crossfire) protocol frames. Commonly used by TBS Crossfire, ExpressLRS, and other RC systems.

Features

• Cross-environment - Works in any JavaScript runtime: Node.js, Bun, Deno, and browsers
• Zero dependencies - Pure TypeScript implementation with no external dependencies
• Transport-agnostic - Designed to work with any byte stream source (serial ports, WebSerial, Bluetooth, WebSocket, etc.)
• Full protocol support - Parses and serializes all standard CRSF frame types including:
  • RC Channels (packed 11-bit, subset)
  • Link Statistics (TX/RX)
  • GPS, GPS Time, GPS Extended
  • Attitude, Barometer, Variometer
  • Battery Sensor, Voltages
  • Magnetometer, Accelerometer/Gyro
  • Flight Mode, Heartbeat, VTX Telemetry
  • And more...
• Type-safe - Full TypeScript support with discriminated unions for frame variants

Installation

# npm
npm install crsf

# yarn
yarn add crsf

# pnpm
pnpm add crsf

# bun
bun add crsf

Usage

Basic Parsing

The library expects a stream of bytes and handles frame detection, validation, and parsing internally. You are responsible for providing the transport layer (serial connection, WebSocket, etc.).

import { CrossfireParser, getFrameVariant, FRAME_TYPE } from 'crsf';

const parser = new CrossfireParser((frame) => {
  const variant = getFrameVariant(frame);

  switch (variant.frameType) {
    case FRAME_TYPE.RC_CHANNELS_PACKED:
      console.log('RC Channels:', {
        ch1: variant.channel1,
        ch2: variant.channel2,
        ch3: variant.channel3,
        ch4: variant.channel4,
        // ... channels 1-16 available
      });
      break;

    case FRAME_TYPE.LINK_STATISTICS:
      console.log('Link Stats:', {
        rssi: variant.puRssiAnt1,
        linkQuality: variant.upLinkQuality,
        snr: variant.upSnr,
      });
      break;

    case FRAME_TYPE.GPS:
      console.log('GPS:', {
        lat: variant.latitude / 10_000_000,
        lon: variant.longitude / 10_000_000,
        altitude: variant.altitude,
        satellites: variant.satellites,
      });
      break;

    case FRAME_TYPE.BATTERY_SENSOR:
      console.log('Battery:', {
        voltage: variant.voltage / 10, // Volts
        current: variant.current / 10, // Amps
        remaining: variant.remaining,  // Percent
      });
      break;
  }
});

// Feed data chunks as they arrive from your transport layer
parser.appendChunk(data); // ArrayBuffer or ArrayBufferView

Serializing Frames

import { serialize, RCChannelsPacked, GPS, BatterySensor } from 'crsf';

// Create RC channels frame
const rcChannels = new RCChannelsPacked(
  1500, 1500, 1000, 1500, // channels 1-4
  1000, 1000, 1000, 1000, // channels 5-8
  1000, 1000, 1000, 1000, // channels 9-12
  1000, 1000, 1000, 1000  // channels 13-16
);

// Serialize to bytes
const bytes = serialize(rcChannels.crossfireFrame);

// Send bytes over your transport layer
serialPort.write(bytes);

Integration Examples

Node.js with SerialPort

import { SerialPort } from 'serialport';
import { CrossfireParser, getFrameVariant, FRAME_TYPE, serialize, RCChannelsPacked } from 'crsf';

const port = new SerialPort({
  path: '/dev/ttyUSB0',
  baudRate: 420000, // CRSF standard baud rate
});

const parser = new CrossfireParser((frame) => {
  const variant = getFrameVariant(frame);
  
  if (variant.frameType === FRAME_TYPE.LINK_STATISTICS) {
    console.log(`RSSI: ${variant.puRssiAnt1} dBm, LQ: ${variant.upLinkQuality}%`);
  }
});

// Receive data
port.on('data', (chunk) => {
  parser.appendChunk(chunk);
});

// Send RC channels
const rcFrame = new RCChannelsPacked(1500, 1500, 1000, 1500);
port.write(serialize(rcFrame.crossfireFrame));

Browser with Web Serial API

import { CrossfireParser, getFrameVariant, FRAME_TYPE } from 'crsf';

async function connectSerial() {
  const port = await navigator.serial.requestPort();
  await port.open({ baudRate: 420000 });

  const parser = new CrossfireParser((frame) => {
    const variant = getFrameVariant(frame);
    console.log('Frame received:', variant.frameType);
  });

  const reader = port.readable.getReader();
  
  while (true) {
    const { value, done } = await reader.read();
    if (done) break;
    parser.appendChunk(value);
  }
}

Deno with Web Serial

import { CrossfireParser, getFrameVariant } from 'npm:crsf';

const port = await navigator.serial.requestPort();
await port.open({ baudRate: 420000 });

const parser = new CrossfireParser((frame) => {
  const variant = getFrameVariant(frame);
  console.log('Received:', variant.constructor.name);
});

for await (const chunk of port.readable) {
  parser.appendChunk(chunk);
}

Supported Frame Types

| Frame Type | Class | Description | | ---------- | ----- | ----------- | | RC_CHANNELS_PACKED | RCChannelsPacked | 16 RC channels (11-bit packed) | | RC_CHANNELS_PACKED_11_BITS | RCChannelsPacked11Bits | Alternative 11-bit packing | | SUBSET_RC_CHANNELS_PACKED | SubsetRCChannelsPacked | Subset of RC channels | | LINK_STATISTICS | LinkStatistics | Link quality metrics | | LINK_STATISTICS_TX | LinkStatisticsTx | TX-specific link stats | | LINK_STATISTICS_RX | LinkStatisticsRx | RX-specific link stats | | GPS | GPS | Position, speed, heading | | GPS_TIME | GPSTime | GPS timestamp | | GPS_EXTENDED | GPSExtended | Extended GPS data | | ATTITUDE | Attitude | Pitch, roll, yaw | | BATTERY_SENSOR | BatterySensor | Voltage, current, capacity | | BAROMETER | Barometer | Pressure, temperature | | BAROMETRIC_ALTITUDE_VERTICAL_SPEED | BarometricAltitudeVerticalSpeed | Altitude & vario | | VARIOMETER_SENSOR | VariometerSensor | Vertical speed | | MAGNETOMETER | Magnetometer | Magnetic field XYZ | | ACCEL_GYRO | AccelGyro | IMU data | | AIRSPEED | Airspeed | Airspeed sensor | | FLIGHT_MODE | FlightMode | Current flight mode | | HEARTBEAT | Heartbeat | Device heartbeat | | VTX_TELEMETRY | VTXTelemetry | VTX settings |

API Reference

CrossfireParser

Main parser class that processes incoming byte streams.

const parser = new CrossfireParser(onFrame: (frame: CrossfireFrame) => void);
parser.appendChunk(data: ArrayBuffer | ArrayBufferView): void;

getFrameVariant(frame: CrossfireFrame)

Converts a raw frame to a typed variant class with parsed fields.

serialize(frame: CrossfireFrame)

Serializes a frame to a Uint8Array ready for transmission.

Frame Variant Classes

Each frame type has a corresponding class (e.g., GPS, RCChannelsPacked, LinkStatistics) that:

• Can be instantiated with field values for serialization
• Provides a crossfireFrame getter for conversion to CrossfireFrame
• Has a static fromFrame() method for parsing
• Has a frameType property matching FRAME_TYPE constants

Protocol Notes

• Standard CRSF baud rate: 420000
• Frame structure: [SYNC] [LENGTH] [TYPE] [PAYLOAD...] [CRC]
• Maximum payload size: 60 bytes
• CRC: CRC8 DVB-S2

License

ISC

References

• TBS CRSF Specification
• ExpressLRS
• ArduPilot CRSF Implementation