starlink-node/README.md

Node.js package for communication and control of Starlink terminals locally

# Starlink Node

A Node.js library for communicating with and controlling Starlink terminals locally via gRPC.

## Features

- 🛰️ Get terminal status and statistics
- 📊 Monitor connection quality and performance metrics
- 🔄 Control terminal operations (reboot, stow/unstow)
- 📈 Real-time telemetry data
- 🌍 Location and obstruction information
- ⚡ High-performance gRPC communication

## Installation

```bash
npm install starlink-node
```

## Quick Start

```typescript
import { StarlinkClient } from 'starlink-node';

const client = new StarlinkClient('192.168.100.1'); // Default Starlink terminal IP

async function main() {
  try {
    // Get terminal status
    const status = await client.getStatus();
    console.log('Terminal Status:', status);

    // Get statistics
    const stats = await client.getStats();
    console.log('Connection Stats:', stats);

    // Get location info
    const location = await client.getLocation();
    console.log('Terminal Location:', location);

  } catch (error) {
    console.error('Error:', error);
  } finally {
    await client.disconnect();
  }
}

main();
```

## API Reference

### StarlinkClient

#### Constructor
- `new StarlinkClient(host?: string, port?: number)`
  - `host` - Starlink terminal IP address (default: '192.168.100.1')
  - `port` - gRPC port (default: 9200)

#### Methods

##### `getStatus(): Promise<TerminalStatus>`
Get the current terminal status including uptime, hardware version, and operational state.

##### `getStats(): Promise<ConnectionStats>`
Get connection statistics including ping, download/upload speeds, and packet loss.

##### `getLocation(): Promise<LocationInfo>`
Get terminal location and obstruction information.

##### `getHistory(): Promise<HistoryData>`
Get historical performance data.

##### `reboot(): Promise<void>`
Reboot the terminal.

##### `stow(): Promise<void>`
Stow the terminal (point straight up).

##### `unstow(): Promise<void>`
Unstow the terminal (resume normal operation).

##### `disconnect(): Promise<void>`
Close the gRPC connection.

## Network Requirements

- Your device must be connected to the Starlink network
- The Starlink terminal must be accessible at `192.168.100.1` (default)
- gRPC port 9200 must be accessible

## Error Handling

The library throws descriptive errors for common issues:

```typescript
try {
  const status = await client.getStatus();
} catch (error) {
  if (error.code === 'UNAVAILABLE') {
    console.error('Cannot connect to Starlink terminal');
  } else if (error.code === 'DEADLINE_EXCEEDED') {
    console.error('Request timed out');
  } else {
    console.error('Unexpected error:', error.message);
  }
}
```

## Examples

See the `examples/` directory for more detailed usage examples.

## Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests.

## License

MIT License - see LICENSE file for details.

## Disclaimer

This is an unofficial library. Use at your own risk. Not affiliated with SpaceX or Starlink.