Skip to content

Commit 29bcdc4

Browse files
1RandomDev1RandomDev
committed
Add readme and docs
1 parent 532f805 commit 29bcdc4

8 files changed

Lines changed: 1153 additions & 0 deletions

File tree

‎LICENSE.md‎

Lines changed: 675 additions & 0 deletions
Large diffs are not rendered by default.

‎README.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# xTool Connect
2+
A community project designed to enable WiFi connectivity for the xTool D1 Pro and possibly other xTool devices like the D1, with LightBurn and other third-party design software.
3+
4+
<p float="left">
5+
<img width="200" src="screenshots/screenshot01.png" />
6+
<img width="200" src="screenshots/screenshot02.png" />
7+
<img width="200" src="screenshots/screenshot03.png" />
8+
<img width="200" src="screenshots/screenshot04.png" />
9+
</p>
10+
11+
## Install & Usage
12+
You can download the Windows and Linux versions from [Releases](https://github.com/1RandomDev/xTool-Connect/releases). \
13+
After installation, your laser is automatically discovered and you can connect to it. The app now lets you modify device settings, move the laser head and control the current print job.
14+
15+
## Upload using LightBurn
16+
Since LightBurn does not support external device plugins right now, this project emulates a generic GRBL laser connected via Serial over TCP. Because of this, certain LightBurn features like Pause, Stop and some advanced controls are currently unsupported. For those functions, use the buttons within the app.\
17+
When using xTool Connect, different start and end GCodes then the ones from the official template are required, therefor it's recommended importing the provided [Template File](xTool-D1-Pro.lbdev).\
18+
\
19+
To upload programs, you can either use the standard "Start" button (slow for more complex programs) or manually save and upload the GCode. Additionally there's a watched file that automatically triggers an upload when overwritten, located at `%AppData%\xTool-Connect\upload.gcode` (Windows) or `~/.local/share/xTool-Connect/upload.gcode` (Linux). Select "Save GCode", navigate to the file for your OS and click overwrite (path will be remembered for the next time).
20+
21+
## Currently Tested Models
22+
- xTool D1 Pro
23+
24+
Don't have any other :C
25+
26+
## xTool API Documentation
27+
In [XTOOL_PROTOCOL](XTOOL_PROTOCOL.md) you can find an almost complete documentation of the xTool D1 Pro HTTP and Websocket API that I reverse engineered from the official app and a binary analysis of the firmware update file.

‎XTOOL_PROTOCOL.md‎

Lines changed: 305 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,305 @@
1+
#### TCP Ports
2+
| Port | Function |
3+
| ---- | --------- |
4+
| 8080 | HTTP API |
5+
| 8081 | WebSocket |
6+
7+
#### HTTP API
8+
##### GET `/progress`
9+
Returns info about the current working state of the machine.
10+
###### Response:
11+
```js
12+
{
13+
"progress": 100.00, // Progress of the current job
14+
"working": 56197, // Time since the current job was started in milliseconds
15+
"line": 0 // Current line of GCODE file
16+
}
17+
```
18+
19+
##### GET `/ping`
20+
Always returns okay if the device is reachable.
21+
###### Response:
22+
```js
23+
{
24+
"result": "ok"
25+
}
26+
```
27+
28+
##### GET `/getmachinetype`
29+
Returns type of the current machine.
30+
###### Response:
31+
```js
32+
{
33+
"result": "ok",
34+
"type": "xTool D1Pro"
35+
}
36+
```
37+
38+
##### GET `/getlaserpowertype`
39+
Returns the maximum power of the installed laser module.
40+
###### Response:
41+
```js
42+
{
43+
"result": "ok",
44+
"power": 10 // 10W
45+
}
46+
```
47+
48+
##### GET `/getlaserpowerinfo`
49+
Returns information about the installed laser module, similar to `/getlaserpowertype`.
50+
###### Response:
51+
```js
52+
{
53+
"result": "ok",
54+
"type": 0, // Maybe 0 for regular laser and 1 for infrared?
55+
"power": 10 // 10W
56+
}
57+
```
58+
59+
##### GET `/peripherystatus`
60+
Returns current status of the machine and current configuration.
61+
###### Response:
62+
```js
63+
{
64+
"result": "ok",
65+
"status": "normal",
66+
"sdCard": 1, // 1 = card inserted, 0 = no card
67+
"limitStopFlag": 1, // 1 = on, 0 = off
68+
"tiltStopFlag": 1, // 1 = on, 0 = off, set by XCS together with movingStopFlag
69+
"movingStopFlag": 1, // 1 = on, 0 = off, set by XCS together with tiltStopFlag
70+
"tiltThreshold": 15, // Threshold for the tilt sensor, not accessible via XCS
71+
"movingThreshold": 40, // Threshold for the movement sensor, not accessible via XCS
72+
"flameAlarmMode": 3, // Don't know what it does, maybe different detection algorithms? Not accessible via XCS.
73+
"flameAlarmSensitivity": 1 // 1 = high, 2 = low, 3 = off
74+
}
75+
```
76+
77+
##### GET `/system`
78+
Used for querying and changing settings of the machine.
79+
###### Parameters:
80+
| Name | Description |
81+
| --------------------- | ----------- |
82+
| action | Action the user wants to perform.<br>Supported actions: mac, version, get_working_sta, offset, dotMode, set_dev_name, get_dev_name, setLimitStopSwitch, setTiltStopSwitch, setMovingStopSwitch, setTiltCheckThreshold, setMovingCheckThreshold, setFlameAlarmMode, setFlameAlarmSensitivity |
83+
| name | Must be used together with `action=set_dev_name` and should contain the new name of the device. |
84+
| limitStopSwitch | Must be used together with `action=setLimitStopSwitch`.<br>Supported values: 1 = on, 0 = off |
85+
| tiltStopSwitch | Must be used together with `action=setTiltStopSwitch`.<br>Supported values: 1 = on, 0 = off |
86+
| movingStopSwitch | Must be used together with `action=setMovingStopSwitch`.<br>Supported values: 1 = on, 0 = off |
87+
| tiltCheckThreshold | Must be used together with `action=setTiltCheckThreshold`.<br>Supported values: 0 - 255; Default: 15 |
88+
| movingCheckThreshold | Must be used together with `action=setMovingCheckThreshold`.<br>Supported values: 0 - 255; Default: 40 |
89+
| tiltStopSwitch | Must be used together with `action=setTiltStopSwitch`.<br>Supported values: 1 = on, 0 = off |
90+
| flameAlarmMode | Must be used together with `action=setFlameAlarmMode`.<br>Supported values: unknown |
91+
| flameAlarmSensitivity | Must be used together with `action=setFlameAlarmSensitivity`.<br>Supported values: 1 = high, 2 = low, 3 = off |
92+
###### Response:
93+
```json
94+
// action=mac
95+
{
96+
"result": "ok",
97+
"mac": "XX:XX:XX:XX:XX:XX"
98+
}
99+
// action=version
100+
{
101+
"result": "ok",
102+
"sn": "XXXXXXXXXXXXXXX",
103+
"version": "V40.31.006.01 B2"
104+
}
105+
// action=get_working_sta
106+
{
107+
"result": "ok",
108+
"working": "0" // 0 = idle, 1 = running (when started via /read API), 2 = running (started via button on device)
109+
}
110+
// action=offset
111+
{
112+
"result": "ok",
113+
"x": 0.0,
114+
"y": 0.0
115+
}
116+
// action=dotMode
117+
{
118+
"result": "ok",
119+
"dotMode": 0
120+
}
121+
// action=get_dev_name
122+
{
123+
"result": "ok",
124+
"name": "My xTool D1 Pro"
125+
}
126+
```
127+
128+
##### GET `/cmd`
129+
Execute a single GCODE command.
130+
###### Parameters:
131+
| Name | Required | Description |
132+
| ---- | -------- | ------------------------------ |
133+
| cmd | Yes | GCODE that should be executed. |
134+
###### Response:
135+
```js
136+
{
137+
"result": "ok"
138+
}
139+
```
140+
141+
##### POST `/cmd`
142+
Execute multiple GCODE commands.
143+
###### Body (plain text):
144+
```
145+
G1
146+
G2
147+
M1
148+
...
149+
```
150+
151+
##### GET `/read`
152+
Read and immediately execute GCODE file from SD card.
153+
###### Parameters:
154+
| Name | Required | Description |
155+
| ---- | -------- | -------------------------------- |
156+
| file | Yes | Path of the file on the SD card. |
157+
###### Response:
158+
```js
159+
{
160+
"result": "ok" // or "fail" if the file cannot be found, if the file exists but cannot be executed machine will return ok while doing nothing
161+
}
162+
```
163+
164+
##### GET `/list`
165+
Returns list of files on the SD card.
166+
###### Parameters:
167+
| Name | Required | Description |
168+
| ---- | -------- | ----------- |
169+
| dir | No | Path to directory that should be listed, defaults to root of the SD card. |
170+
###### Response:
171+
```js
172+
{
173+
"type": "dir",
174+
"name": [
175+
"/frame.gcode",
176+
"/tmp.gcode",
177+
//...
178+
]
179+
}
180+
```
181+
182+
##### GET `/delete`
183+
Delete a file from the SD card.
184+
###### Parameters:
185+
| Name | Required | Description |
186+
| ---- | -------- | ----------- |
187+
| file | Yes | Path of file or directory that should be deleted. Directories can only be deleted once they are empty. |
188+
###### Response:
189+
```js
190+
{
191+
"result": "ok" // or "fail" if the file cannot be found
192+
}
193+
```
194+
195+
##### POST `/upload` or POST `/cnc/data`
196+
Upload a file to the SD card.
197+
###### Parameters:
198+
| Name | Required | Description |
199+
| -------- | -------- | ----------- |
200+
| filetype | No | Type of the GCODE file (frame or program) used for naming the files.<br>Type 0 = /frame.gcode, Type 1 = /tmp.gcode |
201+
| filename | No | Full path where the uploaded file should be placed. Directories need to exist prior to upload.<br>Default: /tmp.gcode |
202+
###### Body (multipart form):
203+
| Name | Required | Description |
204+
| ---- | -------- | ----------- |
205+
| file | Yes | File that should be uploaded. |
206+
###### Response:
207+
```js
208+
{
209+
"result": "ok" // even if something went wrong
210+
}
211+
```
212+
213+
##### GET `/cnc/data`
214+
Pause, resume, stop current job.
215+
###### Parameters:
216+
| Name | Required | Description |
217+
| ------ | -------- | ----------- |
218+
| action | Yes | Action the user wants to perform.<br>Supported actions: pause, resume, stop |
219+
###### Response:
220+
```js
221+
{
222+
"result": "ok" // or "fail" is action is not possible in the current state
223+
}
224+
```
225+
226+
##### GET `/updater`
227+
Simple web interface that lets the user upload a custom firmware update.
228+
229+
##### POST `/upgrade`
230+
Endpoint for uploading firmware update. Used by the web based updater and XCS.
231+
###### Body (multipart form):
232+
| Name | Required | Description |
233+
| ---- | -------- | --------------------- |
234+
| file | Yes | Firmware binary file. |
235+
**Response:**
236+
`OK` or `FAIL` in plain Text
237+
238+
##### GET `/framing`
239+
Usage unknown since framing is usually done via the `/cnc/data` endpoint.
240+
241+
#### WiFi Setup
242+
When holding down the power button for 5 seconds in idle, the machine will enter WiFi setup mode. To access the following API endpoints the user must be connected to the AP starting with `xTool_D1P_`. The xTool will be accessible via the ip `192.168.40.1`.
243+
##### POST `http://192.168.40.1:8080/net?action=connsta`
244+
Set WiFi configuration.
245+
###### Body (plain text):
246+
```
247+
<SSID> <PASSWORD>
248+
```
249+
###### Response:
250+
```js
251+
{
252+
"result": "ok"
253+
}
254+
```
255+
256+
#### WebSocket API
257+
##### Messages from the machine
258+
| Name | Description |
259+
| -------------------- | ----------- |
260+
| ok:IDLE | Machine finished a job or job was aborted and is now in idle again. |
261+
| ok:WORKING_\<state\> | Machine entered working state, available states are WORKING_ONLINE, WORKING_ONLINE_READY, WORKING_OFFLINE, WORKING_FRAMING, WORKING_FRAME_READY. |
262+
| ok:PAUSING | Current job paused either via the button or via the API. |
263+
| WORK_STOPPED | Current job has been canceled by holding the power button for 3s or API. |
264+
| ok:ERROR | An error occurred. |
265+
| err:tiltCheck | Tilt sensor exceeded threshold. |
266+
| err:movingCheck | Movement sensor exceeded threshold. |
267+
| err:limitCheck | Limit switch was activated. |
268+
| err:flameCheck | Flame was detected. |
269+
270+
#### Discovery
271+
##### UDP Broadcast
272+
Broadcast message:
273+
```js
274+
{
275+
"ip": "192.168.178.211", // Address of the current computer
276+
"port": 20000,
277+
"requestId": 123456 // Request ID (will be included in the response for identification)
278+
}
279+
```
280+
281+
Example:
282+
```bash
283+
$ echo '{"requestId":123456}' | socat - UDP-DATAGRAM:255.255.255.255:20000,broadcast
284+
285+
{
286+
"requestId": 123456,
287+
"ip": "192.168.178.229",
288+
"name": "xTool D1 Pro",
289+
"version": "40.31.006.01"
290+
}
291+
```
292+
293+
294+
#### GCODE
295+
Incomplete right now.
296+
| Code | Description |
297+
| -------------- | ----------------------------- |
298+
| M28 | Move to home position |
299+
| M106 S0/1 | Enable/Disable laser cross |
300+
| M17 | Enable steppers |
301+
| M18 | Disable steppers/laser module |
302+
| M205 X... Y... | Set working area |
303+
| M101 | Flat surface mode |
304+
| M102 | Rotary mode |
305+
| G92 X... Y... | Set origin |

‎screenshots/screenshot01.png‎

26.1 KB
Loading

‎screenshots/screenshot02.png‎

39.9 KB
Loading

‎screenshots/screenshot03.png‎

61.7 KB
Loading

‎screenshots/screenshot04.png‎

47.6 KB
Loading

0 commit comments

Comments
 (0)