Skip to content

Commit 43ce613

Browse files
GhostTypesGhostTypes
authored
Revise README for improved clarity and organization
Updated README to enhance clarity and structure, added detailed sections for printer coverage, feature coverage, and getting started instructions.
1 parent 2ba8a15 commit 43ce613

1 file changed

Lines changed: 149 additions & 96 deletions

File tree

‎README.md‎

Lines changed: 149 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,138 @@
1-
# 🖨️ FlashForge TypeScript API
2-
3-
> 🔧 A robust, cross-platform API for FlashForge 3D printers, created through reverse-engineering of the communication between the printer(s) and FlashForge software.
4-
5-
## 🌟 About
6-
7-
Built upon the foundation of my previous [C# API](https://github.com/GhostTypes/ff-5mp-api), this TypeScript implementation is designed for **easier cross-platform usage and development**.
8-
9-
---
10-
11-
## 🖨️ Printer Coverage & Testing
12-
| 🖨️ Printer | ✅ Supported | 🧪 Tested | 🔌 API |
13-
|-------------|--------------|-----------|--------|
14-
| **Adventurer 5X** | ⚠️ Basic | ✅ Yes | HTTP (New) + TCP (Additional Features) |
15-
| **Adventurer 5M/Pro** | ✅ Yes | ✅ Yes | HTTP (New) + TCP (Additional Features) |
16-
| **Adventurer 3/4** | ✅ Yes | 🔄 Partially | TCP (Legacy Mode) |
17-
18-
---
19-
20-
## ⚡ Feature Coverage
21-
22-
> 💡 **Legacy Mode** covers all network-enabled printers before the Adventurer 5 series
23-
24-
| 🔧 Feature | 🔄 Legacy Mode | 🆕 "New" API |
25-
|------------|----------------|---------------|
26-
| 📁 **Get Recent & Local Files** | ✅ Yes | ✅ Yes |
27-
| 🖼️ **Get Model Preview Images** | ✅ Yes (Slow) | ⚡ Yes (Fast!) |
28-
| 🎮 **Full Job Control** (Start, Stop, Pause, Resume, etc.) | ✅ Yes | ✅ Yes |
29-
| 💡 **LED Control** (On/Off) | ✅ Yes | ✅ Yes |
30-
| 📤 **Uploading New Files** | ❌ No (Not planned) | ✅ Yes |
31-
| ℹ️ **Printer Information** | ⚠️ Limited | ✅ Yes |
32-
| 📊 **(Extra) Job Information** | ⚠️ Very Limited | ✅ Yes |
33-
| ⏰ **Job Time & ETA** | ❌ Not Available | ✅ Yes |
34-
| 🏠 **Homing/Direct G&M Code Control** | ✅ Yes | ✅ Yes |
35-
36-
---
37-
38-
## 🚀 Getting Started
39-
40-
This guide will walk you through using the API with different generations of FlashForge printers.
41-
42-
### Legacy Printers (Adventurer 3/4, etc.)
43-
44-
Older FlashForge printers use a "legacy" TCP-based API. This API is more limited but still provides core functionality like job control and status monitoring.
45-
46-
To connect to a legacy printer, you only need its IP address.
1+
<div align="center">
2+
<h1>FlashForge TypeScript API</h1>
3+
<p>
4+
A robust, cross-platform API for FlashForge 3D printers, created through
5+
reverse-engineering the communication between the printers and FlashForge software.
6+
</p>
7+
</div>
8+
9+
10+
<br>
11+
<div align="center">
12+
<h2>Printer Coverage & Testing</h2>
13+
</div>
14+
15+
<div align="center">
16+
<table>
17+
<tr>
18+
<th>Printer</th>
19+
<th>Supported</th>
20+
<th>Tested</th>
21+
<th>API</th>
22+
</tr>
23+
24+
<tr>
25+
<td><strong>Adventurer 5X</strong></td>
26+
<td>Yes</td>
27+
<td>Yes</td>
28+
<td>HTTP + TCP</td>
29+
</tr>
30+
31+
<tr>
32+
<td><strong>Adventurer 5M / 5M Pro</strong></td>
33+
<td>Yes</td>
34+
<td>Yes</td>
35+
<td>HTTP + TCP</td>
36+
</tr>
37+
38+
<tr>
39+
<td><strong>Adventurer 3 / 4</strong></td>
40+
<td>Yes</td>
41+
<td>Partial</td>
42+
<td>TCP Only</td>
43+
</tr>
44+
</table>
45+
</div>
46+
47+
<br>
48+
49+
<div align="center">
50+
<h2>Feature Coverage</h2>
51+
</div>
52+
53+
<div align="center">
54+
<table>
55+
<tr>
56+
<th>Feature</th>
57+
<th>TCP Only</th>
58+
<th>TCP + HTTP</th>
59+
</tr>
60+
61+
<tr>
62+
<td>Get Recent & Local Files</td>
63+
<td>Yes</td>
64+
<td>Yes</td>
65+
</tr>
66+
67+
<tr>
68+
<td>Model Preview Images</td>
69+
<td>Yes (Slow)</td>
70+
<td>Yes (Fast)</td>
71+
</tr>
72+
73+
<tr>
74+
<td>Full Job Control<br><small>(Start / Stop / Pause / Resume)</small></td>
75+
<td>Yes</td>
76+
<td>Yes</td>
77+
</tr>
78+
79+
<tr>
80+
<td>LED Control</td>
81+
<td>Yes</td>
82+
<td>Yes</td>
83+
</tr>
84+
85+
<tr>
86+
<td>Upload New Files</td>
87+
<td>No (Not planned)</td>
88+
<td>Yes</td>
89+
</tr>
90+
91+
<tr>
92+
<td>Printer Information</td>
93+
<td>Limited</td>
94+
<td>Yes</td>
95+
</tr>
96+
97+
<tr>
98+
<td>Job Information</td>
99+
<td>Very Limited</td>
100+
<td>Yes</td>
101+
</tr>
102+
103+
<tr>
104+
<td>Job Time & ETA</td>
105+
<td>Not Available</td>
106+
<td>Yes</td>
107+
</tr>
108+
109+
<tr>
110+
<td>Homing / Direct G&M Code Control</td>
111+
<td>Yes</td>
112+
<td>Yes</td>
113+
</tr>
114+
</table>
115+
</div>
116+
117+
<br>
118+
119+
<div align="center">
120+
<h2>Getting Started</h2>
121+
<p>
122+
This section covers how to use the API with both legacy FlashForge printers and
123+
newer models such as the Adventurer 5M / 5M Pro and AD5X.
124+
</p>
125+
</div>
126+
127+
<br>
128+
129+
<div align="center">
130+
<h3>Legacy Printers (Adventurer 3 / 4)</h3>
131+
<p>
132+
Legacy FlashForge printers use a TCP-based protocol which provides basic job control,
133+
printer information, and status monitoring. Connecting only requires the printer’s IP address.
134+
</p>
135+
</div>
47136

48137
```typescript
49138
import { FlashForgeClient } from 'ff-api';
@@ -65,7 +154,6 @@ async function main() {
65154
console.log(`Firmware: ${info.FirmwareVersion}`);
66155
}
67156

68-
// Remember to dispose of the client when done
69157
await client.dispose();
70158
} else {
71159
console.log("Failed to connect to printer.");
@@ -74,20 +162,11 @@ async function main() {
74162

75163
main();
76164
```
77-
78-
**Functionality Notes:**
79-
- **Basic Control:** Full control over starting, stopping, and pausing jobs.
80-
- **Status Monitoring:** Get basic printer info, temperature, and job progress.
81-
- **No File Uploads:** The legacy API does not support uploading files. You must print files already on the printer.
82-
- **Slower Thumbnails:** Retrieving model preview images can be slow.
83-
84-
---
85-
86-
### Adventurer 5M / 5M Pro
87-
88-
The Adventurer 5 series introduced a new, more powerful HTTP-based API, while retaining the legacy TCP API for specific features like direct G-code control. This hybrid approach offers the best of both worlds.
89-
90-
To connect, you'll need the printer's IP address, serial number, and a "check code". These can be found in the printer's network settings.
165+
<br>
166+
<div align="center">
167+
<h3>Adventurer 5M / 5M Pro</h3>
168+
<p> The Adventurer 5 series uses an improved HTTP API for fast, modern communication, while still supporting legacy TCP-based G-code control. You will need the printer’s <strong>IP address</strong>, <strong>serial number</strong>, and <strong>check code</strong></p>
169+
</div>
91170

92171
```typescript
93172
import { FiveMClient } from 'ff-api';
@@ -126,25 +205,11 @@ async function main() {
126205
main();
127206
```
128207

129-
**Functionality Notes:**
130-
- **All Legacy Features:** Includes all capabilities of the legacy API.
131-
- **File Uploads:** Easily upload G-code files directly to the printer.
132-
- **Rich Information:** Access detailed information about the printer, job status, and print time estimates.
133-
- **Fast Thumbnails:** Model previews are retrieved quickly over the HTTP API.
134-
135-
---
136-
137-
### Adventurer 5X (AD5X)
138-
139-
The AD5X uses the same powerful HTTP API as the 5M series but adds specialized support for its **Intelligent Filament Station (IFS)**, enabling multi-color and multi-material printing. The API provides dedicated methods and data models to manage this functionality.
140-
141-
Connecting to an AD5X is identical to a standard 5M.
142-
143-
#### Checking the Material Station (IFS)
144-
145-
After connecting, you can get detailed information about the Intelligent Filament Station. The `FFMachineInfo` object, accessible via `client.info.machineInfo` after a successful connection, contains all the details.
146-
147-
The `MatlStationInfo` property provides a comprehensive status of the IFS, including the state of each slot.
208+
<div align="center">  
209+
<h3>Adventurer 5X (AD5X)</h3>  
210+
<p>The AD5X uses the same powerful HTTP API as the 5M series but adds specialized support for its <strong>Intelligent Filament Station (IFS)</strong>, enabling multi-color and multi-material printing. The API provides dedicated methods and data models to manage this functionality.</p>  
211+
<p> Connecting to an AD5X is identical to a standard 5M. </p>
212+
</div>
148213

149214
```typescript
150215
import { FiveMClient } from 'ff-api';
@@ -183,12 +248,10 @@ async function checkIFS() {
183248
checkIFS();
184249
```
185250

186-
#### Starting a Multi-Color Print
251+
<div align="center">   <h4>Starting a Multi-Color Print</h4>   <p>     To start a multi-color print, you need to provide <code>materialMappings</code>. This array links the tool ID from your G-code file to a specific slot in the material station.   </p>   <p>         - <code>toolId</code>: The tool index from your slicing software (0-3).        
187252

188-
To start a multi-color print, you need to provide `materialMappings`. This array links the tool ID from your G-code file to a specific slot in the material station.
189253

190-
- `toolId`: The tool index from your slicing software (0-3).
191-
- `slotId`: The physical slot on the material station (1-4).
254+
- <code>slotId</code>: The physical slot on the material station (1-4).   </p> </div>
192255

193256
```typescript
194257
import { FiveMClient, AD5XLocalJobParams, AD5XMaterialMapping } from 'ff-api';
@@ -219,9 +282,7 @@ async function startMultiColor() {
219282
}
220283
```
221284

222-
#### Starting a Single-Color Print
223-
224-
For single-color prints, you can use a simpler method that doesn't require material mappings. The printer will use the currently loaded filament.
285+
<div align="center">   <h4>Starting a Single-Color Print</h4>   <p>     For single-color prints, you can use a simpler method that doesn't require material mappings. The printer will use the currently loaded filament.   </p> </div>
225286

226287
```typescript
227288
import { FiveMClient, AD5XSingleColorJobParams } from 'ff-api';
@@ -246,13 +307,5 @@ async function startSingleColor() {
246307
}
247308
```
248309

249-
#### Uploading Files for AD5X
250-
251-
You can also upload files with material mappings directly using `uploadFileAD5X`. The `materialMappings` are Base64-encoded and sent in the headers automatically.
310+
<div align="center">   <h4>Uploading Files for AD5X</h4>   <p>     You can also upload files with material mappings directly using <code>uploadFileAD5X</code>. The material mappings are Base64-encoded and sent in the headers automatically.  </p> </div>
252311

253-
**Functionality Notes:**
254-
- **All 5M/Pro Features:** Inherits all functionality from the standard 5M series.
255-
- **Intelligent Filament Station (IFS):** Provides detailed status and control over the multi-material station.
256-
- **Material Mapping:** Allows precise control over which filament is used for each part of a multi-material print.
257-
- **Dedicated Job Methods:** Separate, validated methods for starting single-color and multi-color jobs simplify development.
258-

0 commit comments

Comments
 (0)