Merge pull request #13 from GhostTypes/docs-update

Add comprehensive API documentation

Author: GhostTypes

docs/README.md

@@ -0,0 +1,77 @@
+# FlashForge API Documentation
+
+Welcome to the comprehensive documentation for the FlashForge API. This library provides a robust interface for interacting with FlashForge 3D printers, supporting both legacy TCP-based communication and the newer HTTP API used by 5M, 5M Pro, and Adventurer 5X (AD5X) series printers.
+
+## Table of Contents
+
+1. [Getting Started](#getting-started)
+2. [Architecture Overview](#architecture-overview)
+3. [Client Documentation](clients.md)
+4. [Models & Interfaces](models.md)
+5. [Modules & Namespaces](modules.md)
+6. [Protocols](protocols.md)
+7. [Error Handling](errors.md)
+8. [Advanced Topics](advanced.md)
+
+## Getting Started
+
+### Installation
+
+```bash
+npm install @ghosttypes/ff-api
+```
+
+### Discovery
+
+To start interacting with a printer, you first need to discover it on your local network.
+
+```typescript
+import { FlashForgePrinterDiscovery } from '@ghosttypes/ff-api';
+
+const discovery = new FlashForgePrinterDiscovery();
+const printers = await discovery.discoverPrintersAsync();
+
+printers.forEach(printer => {
+    console.log(`Found printer: ${printer.name} at ${printer.ipAddress}`);
+});
+```
+
+### connecting to a Printer
+
+Once you have the printer's IP address, serial number, and check code (usually provided by the discovery or known beforehand), you can instantiate a client.
+
+**For newer printers (5M, 5M Pro, AD5X):**
+
+```typescript
+import { FiveMClient } from '@ghosttypes/ff-api';
+
+const client = new FiveMClient("192.168.1.100", "SERIAL123", "CHECKCODE123");
+const connected = await client.initialize();
+
+if (connected) {
+    console.log("Connected!");
+    await client.initControl(); // Initialize control connection
+}
+```
+
+**For legacy printers (Adventurer 3/4, etc.):**
+
+```typescript
+import { FlashForgeClient } from '@ghosttypes/ff-api';
+
+const client = new FlashForgeClient("192.168.1.100");
+const connected = await client.initControl();
+
+if (connected) {
+    console.log("Connected to legacy printer!");
+}
+```
+
+## Architecture Overview
+
+The library is built around two main client classes:
+
+- **`FiveMClient`**: Designed for the Adventurer 5M series and AD5X. It primarily uses an HTTP API for state management, file operations, and job control, while falling back to TCP for specific real-time commands.
+- **`FlashForgeClient`**: A TCP-based client that communicates using FlashForge's G-code/M-code protocol. This is used for legacy printers and is also wrapped by `FiveMClient` for low-level operations.
+
+For detailed API usage, refer to the [Client Documentation](clients.md).

docs/advanced.md

@@ -0,0 +1,75 @@
+# Advanced Topics
+
+## Multi-Color Printing (AD5X)
+
+The Adventurer 5X (AD5X) supports multi-material printing via its Intelligent Filament Station (IFS). The API allows you to map tools (extruders) in your G-code to specific slots in the IFS.
+
+### Material Mapping
+
+To start a multi-color print, you need to define `AD5XMaterialMapping` objects.
+
+```typescript
+import { AD5XMaterialMapping } from '@ghosttypes/ff-api';
+
+const mappings: AD5XMaterialMapping[] = [
+    {
+        toolId: 0,            // The first tool in the G-code
+        slotId: 1,            // Use filament from Slot 1
+        materialName: "PLA",
+        toolMaterialColor: "#FF0000", // Color defined in slicer
+        slotMaterialColor: "#FF0000"  // Actual color in slot
+    },
+    {
+        toolId: 1,
+        slotId: 2,
+        materialName: "PLA",
+        toolMaterialColor: "#0000FF",
+        slotMaterialColor: "#0000FF"
+    }
+];
+```
+
+### Starting a Job
+
+You can start a job with these mappings using `startAD5XMultiColorJob` (for local files) or `uploadFileAD5X` (for new uploads).
+
+```typescript
+await client.jobControl.startAD5XMultiColorJob({
+    fileName: "multi_color_model.gcode",
+    levelingBeforePrint: true,
+    materialMappings: mappings
+});
+```
+
+## Direct G-Code Control
+
+For advanced users, you may need to send raw G-code commands that aren't exposed by the high-level API. You can access the underlying `FlashForgeClient` via `client.tcpClient`.
+
+```typescript
+// Send a raw G-code command
+const response = await client.tcpClient.sendRawCmd("~G1 X100 Y100 F3000");
+console.log(response); // Output from printer
+```
+
+*Note: Use raw commands with caution. Incorrect G-code can damage the printer.*
+
+## Image Preview Handling
+
+The API allows retrieving thumbnail previews for G-code files. This is useful for building UI applications.
+
+```typescript
+const thumbnailBuffer = await client.files.getGCodeThumbnail("model.gcode");
+
+if (thumbnailBuffer) {
+    // Save to file
+    fs.writeFileSync("preview.png", thumbnailBuffer);
+
+    // Or convert to base64 for web display
+    const base64Image = thumbnailBuffer.toString('base64');
+    const imgSrc = `data:image/png;base64,${base64Image}`;
+}
+```
+
+## Firmware Version Handling
+
+The library automatically detects the printer's firmware version. Some features (especially file uploads and print starting) have different payload requirements for newer firmware versions (>= 3.1.3). The `JobControl` class handles this logic internally, so you generally don't need to worry about it. However, if you encounter issues with a specific firmware version, check `client.firmVer`.

docs/clients.md

@@ -0,0 +1,144 @@
+# Client Documentation
+
+This section documents the primary client classes used to interact with FlashForge printers.
+
+## FiveMClient
+
+The `FiveMClient` is the modern interface for Adventurer 5M, 5M Pro, and Adventurer 5X (AD5X) printers. It combines HTTP API calls with a TCP connection for comprehensive control.
+
+### Constructor
+
+```typescript
+constructor(ipAddress: string, serialNumber: string, checkCode: string)
+```
+
+- **`ipAddress`** (`string`): The local IP address of the printer.
+- **`serialNumber`** (`string`): The printer's serial number (required for authentication).
+- **`checkCode`** (`string`): The check code for authentication.
+
+### Properties
+
+- **`control`** (`Control`): Interface for general printer controls (home, fans, LEDs, etc.).
+- **`jobControl`** (`JobControl`): Interface for managing print jobs (start, stop, pause, file upload).
+- **`info`** (`Info`): Interface for retrieving machine status and details.
+- **`files`** (`Files`): Interface for file management (list files, get thumbnails).
+- **`tempControl`** (`TempControl`): Interface for temperature management.
+- **`tcpClient`** (`FlashForgeClient`): The underlying TCP client instance.
+- **`printerName`** (`string`): The configured name of the printer.
+- **`isPro`** (`boolean`): True if the printer is a Pro model.
+- **`isAD5X`** (`boolean`): True if the printer is an AD5X model.
+- **`firmwareVersion`** (`string`): The full firmware version string.
+- **`ledControl`** (`boolean`): True if LED control is available/enabled.
+- **`filtrationControl`** (`boolean`): True if filtration control is available/enabled.
+
+### Key Methods
+
+#### `initialize()`
+
+```typescript
+public async initialize(): Promise<boolean>
+```
+
+Initializes the client by verifying the connection to the printer. Returns `true` if successful.
+
+#### `initControl()`
+
+```typescript
+public async initControl(): Promise<boolean>
+```
+
+Fully initializes control capabilities by authenticating via the product command and establishing the TCP connection. Must be called before performing control actions.
+
+#### `verifyConnection()`
+
+```typescript
+public async verifyConnection(): Promise<boolean>
+```
+
+Checks connectivity by attempting to fetch printer details. Updates cached machine info.
+
+#### `dispose()`
+
+```typescript
+public async dispose(): Promise<void>
+```
+
+Cleanly closes connections and stops background keep-alive processes.
+
+---
+
+## FlashForgeClient
+
+The `FlashForgeClient` is a TCP-based client for legacy printers or low-level G-code operations. It extends `FlashForgeTcpClient`.
+
+### Constructor
+
+```typescript
+constructor(hostname: string)
+```
+
+- **`hostname`** (`string`): The IP address or hostname of the printer.
+
+### Key Methods
+
+#### `initControl()`
+
+```typescript
+public async initControl(): Promise<boolean>
+```
+
+Establishes the TCP connection, logs in, and starts the keep-alive loop.
+
+#### `getPrinterInfo()`
+
+```typescript
+public async getPrinterInfo(): Promise<PrinterInfo | null>
+```
+
+Retrieves basic printer information (firmware, machine type, etc.).
+
+#### `getTempInfo()`
+
+```typescript
+public async getTempInfo(): Promise<TempInfo | null>
+```
+
+Gets current extruder and bed temperatures.
+
+#### `move(x, y, z, feedrate)`
+
+```typescript
+public async move(x: number, y: number, z: number, feedrate: number): Promise<boolean>
+```
+
+Moves the print head to the specified absolute coordinates.
+
+#### `setExtruderTemp(temp, waitFor)`
+
+```typescript
+public async setExtruderTemp(temp: number, waitFor: boolean = false): Promise<boolean>
+```
+
+Sets the extruder target temperature.
+
+---
+
+## FlashForgePrinterDiscovery
+
+A utility class for finding printers on the local network.
+
+### Methods
+
+#### `discoverPrintersAsync()`
+
+```typescript
+public async discoverPrintersAsync(timeoutMs: number = 10000, idleTimeoutMs: number = 1500, maxRetries: number = 3): Promise<FlashForgePrinter[]>
+```
+
+Broadcasts a discovery packet via UDP and listens for responses.
+
+- **`timeoutMs`**: Max time to wait for responses.
+- **`idleTimeoutMs`**: Time to wait after the last response before returning.
+- **`maxRetries`**: Number of broadcast attempts if no printers are found initially.
+
+**Returns:** An array of `FlashForgePrinter` objects containing IP, Serial, and Name.

docs/errors.md

@@ -0,0 +1,37 @@
+# Error Handling
+
+The library uses a combination of return values and exceptions to handle errors.
+
+## Connection Errors
+
+- **Initialization Failure**: `initialize()` or `initControl()` methods will return `false` if the connection cannot be established or verified.
+- **Network Errors**: Lower-level network issues (timeouts, unreachable host) are often caught and logged to the console, with the method returning `null` or `false`.
+- **Keep-Alive Failures**: The TCP client maintains a keep-alive loop. If it fails repeatedly, the connection is considered lost, and the client may attempt to reconnect or stop the keep-alive process.
+
+## API Errors
+
+- **HTTP Status Codes**: The `FiveMClient` checks HTTP status codes. Non-200 responses are treated as failures.
+- **Printer Error Codes**: The `FFMachineInfo` object contains an `ErrorCode` property. This string comes directly from the printer and indicates internal hardware or firmware errors (e.g., "File Error", "Sensor Error").
+
+## Best Practices
+
+1. **Check Return Values**: Most control methods return a `boolean` indicating success or failure. Always check this result.
+   ```typescript
+   if (!await client.control.setLedOn()) {
+       console.error("Failed to turn on LED");
+   }
+   ```
+
+2. **Handle Nulls**: Data retrieval methods (like `info.get()`) may return `null` if the request fails.
+   ```typescript
+   const status = await client.info.get();
+   if (status) {
+       console.log(status.Status);
+   } else {
+       console.log("Could not retrieve status");
+   }
+   ```
+
+3. **Verify Connection**: Before performing critical operations, you can use `client.verifyConnection()` to ensure the printer is still reachable.
+
+4. **Try-Catch**: When using methods that perform file I/O (like `uploadFile`), wrap calls in a `try-catch` block to handle file system errors.