ADVANCED_SYSTEM_GUIDE.md

355 lines · 8.8 KB

Open raw

Copy & run

wget https://perlytiara.github.io/turtles.tips/raw/programs/perlytiara/tClear/ADVANCED_SYSTEM_GUIDE.md
1# Advanced Wireless Mining System - Complete Guide
2
3## 🚀 Overview
4
5The Advanced Wireless Mining System is a comprehensive solution for automated mining operations using ComputerCraft turtles. It features a computer-controlled master system that coordinates mining turtles and chunky turtles for optimal performance and safety.
6
7## 🏗️ System Architecture
8
9```
10[Computer] ← Master Controller
11 ↓
12[Wireless Network]
13 ↓
14[Mining Turtle] ← Left Corner Position
15 ↓
16[Chunky Turtle] ← Right Side (1 block right of mining turtle)
17```
18
19## 📋 Components
20
21### 1. AdvancedMiningController.lua
22- **Purpose**: Master controller running on a computer
23- **Features**:
24 - Automatic turtle discovery
25 - Real-time operation monitoring
26 - Pause/resume controls
27 - Status reporting
28 - Multi-turtle coordination
29
30### 2. AdvancedMiningTurtle.lua
31- **Purpose**: Enhanced mining turtle with wireless communication
32- **Features**:
33 - Remote control capability
34 - Real-time status updates
35 - Chunky turtle coordination
36 - Pause/resume support
37 - Error handling and recovery
38
39### 3. AdvancedChunkyTurtle.lua
40- **Purpose**: Enhanced chunky turtle for chunk loading
41- **Features**:
42 - Improved following behavior
43 - Better error handling
44 - Status reporting
45 - Automatic recovery from movement failures
46
47## 🛠️ Setup Instructions
48
49### Step 1: Hardware Requirements
50
51**Computer (Master Controller):**
52- ComputerCraft computer
53- Wireless modem
54- Monitor (optional, for better interface)
55
56**Mining Turtle:**
57- Advanced mining turtle
58- Wireless modem
59- Pickaxe (or other mining tool)
60- Fuel (coal, charcoal, etc.)
61
62**Chunky Turtle:**
63- Wireless turtle
64- Wireless modem
65- No tools required
66- Fuel (coal, charcoal, etc.)
67
68### Step 2: Placement
69
70```
71[Chunky] [Mining] ← Start here
72 ↓ ↓
73 Turtle Turtle
74```
75
761. Place the **mining turtle** at the left corner of your desired mining area
772. Place the **chunky turtle** one block to the **right** of the mining turtle
783. Both turtles should be at the **same height** and **facing the same direction**
794. Ensure both turtles have wireless modems attached
80
81### Step 3: Software Installation
82
83Copy the following files to the appropriate devices:
84
85**On the Computer:**
86- `AdvancedMiningController.lua`
87
88**On the Mining Turtle:**
89- `AdvancedMiningTurtle.lua`
90
91**On the Chunky Turtle:**
92- `AdvancedChunkyTurtle.lua`
93
94### Step 4: Get Device IDs
95
96On each device, run:
97```lua
98print(os.getComputerID())
99```
100
101Note down all three IDs:
102- Computer ID
103- Mining Turtle ID
104- Chunky Turtle ID
105
106## 🎮 Usage Guide
107
108### Quick Start
109
1101. **Start the Chunky Turtle:**
111 ```lua
112 AdvancedChunkyTurtle
113 ```
114 The chunky turtle will display "Waiting for pairing with master turtle..."
115
1162. **Start the Mining Turtle:**
117 ```lua
118 AdvancedMiningTurtle
119 ```
120 The mining turtle will display "Waiting for controller commands..."
121
1223. **Start the Master Controller:**
123 ```lua
124 AdvancedMiningController
125 ```
126 Follow the on-screen prompts to:
127 - Discover and select turtles
128 - Configure mining parameters
129 - Start the operation
130
131### Operation Parameters
132
133**Basic Parameters:**
134- **Depth**: How far forward to mine (must be ≥ 1)
135- **Width**: How wide to mine (cannot be -1, 0, or 1)
136- **Height**: How tall to mine (cannot be 0)
137
138**Advanced Options:**
139- `layerbylayer` - Mine one layer at a time (safer for lava)
140- `startwithin` - Start inside the mining area
141- `stripmine` - Use for strip mining operations
142
143### Example Commands
144
145```lua
146# Basic mining operation
147Depth: 10
148Width: 5
149Height: 3
150Options: (none)
151
152# Safe mining with layer-by-layer
153Depth: 20
154Width: 8
155Height: 4
156Options: layerbylayer
157
158# Strip mining
159Depth: 50
160Width: -2
161Height: 3
162Options: stripmine layerbylayer
163```
164
165## 📊 Monitoring and Control
166
167### Real-time Monitoring
168
169During operation, you can:
170- Press `s` for status updates
171- Press `p` to pause the operation
172- Press `r` to resume the operation
173- Press `q` to quit monitoring (operation continues)
174
175### Status Information
176
177The system provides real-time information about:
178- Current position of mining turtle
179- Mining progress
180- Fuel levels
181- Inventory status
182- Chunky turtle status
183
184## 🔧 Advanced Features
185
186### Automatic Discovery
187
188The system automatically discovers available turtles on the network:
189- Scans for mining turtles
190- Scans for chunky turtles
191- Displays fuel and inventory information
192- Allows selection of specific turtles
193
194### Error Handling
195
196**Mining Turtle:**
197- Automatic fuel management
198- Movement retry logic
199- Error reporting to controller
200- Graceful operation shutdown
201
202**Chunky Turtle:**
203- Movement failure recovery
204- Digging when blocked
205- Retry logic for failed movements
206- Status reporting
207
208### Communication Protocols
209
210The system uses multiple communication protocols:
211- `advanced-mining` - Main control protocol
212- `tclear-chunky` - Chunky turtle specific protocol
213- Automatic fallback to legacy protocols
214
215## 🚨 Troubleshooting
216
217### Common Issues
218
219**"No mining turtles found"**
220- Ensure mining turtle is running `AdvancedMiningTurtle.lua`
221- Check wireless modem is attached and working
222- Verify both devices are on the same network
223
224**"No chunky turtles found"**
225- Ensure chunky turtle is running `AdvancedChunkyTurtle.lua`
226- Check wireless modem is attached and working
227- Operation can continue without chunky turtle (not recommended)
228
229**"No modem found"**
230- Attach a wireless modem to the device
231- Ensure modem is properly connected
232- Check modem is not damaged
233
234**Chunky turtle not following**
235- Check rednet communication between turtles
236- Restart both turtles if needed
237- Verify turtle IDs are correct
238- Check for obstacles blocking chunky turtle
239
240**Mining turtle breaks during operation**
241- This should not happen with chunky pairing
242- Check that chunky turtle is actually following
243- Ensure chunk loading signals are being sent
244- Verify both turtles have adequate fuel
245
246### Debug Mode
247
248To enable debug output, edit the respective script files:
249```lua
250local blnDebugPrint = true
251```
252
253### Manual Recovery
254
255If the system fails:
2561. Stop all devices (Ctrl+T)
2572. Restart chunky turtle first: `AdvancedChunkyTurtle`
2583. Restart mining turtle: `AdvancedMiningTurtle`
2594. Restart controller: `AdvancedMiningController`
260
261## 📈 Performance Tips
262
263### Optimal Placement
264- Place chunky turtle exactly one block to the right of mining turtle
265- Ensure clear path for chunky turtle to follow
266- Avoid placing near lava or dangerous areas
267- Keep both turtles at the same height
268
269### Fuel Management
270- Keep both turtles well-fueled
271- Monitor fuel levels during operation
272- Have backup fuel ready
273- Use efficient fuel sources (coal, charcoal)
274
275### Network Optimization
276- Ensure good wireless signal strength
277- Avoid interference from other wireless devices
278- Keep devices within reasonable range
279- Use wired modems for long-distance operations
280
281## 🔒 Safety Considerations
282
283### Operation Safety
284- Always test in a safe area first
285- Monitor the operation, especially for large excavations
286- Keep backup fuel for both turtles
287- Ensure adequate inventory space
288
289### Turtle Safety
290- The chunky turtle is vulnerable while following
291- Protect chunky turtle from mobs
292- Avoid dangerous areas (lava, void, etc.)
293- Keep both turtles fueled and maintained
294
295### Emergency Procedures
296- Press Ctrl+T on any device to stop
297- Both turtles will stop safely
298- Manual recovery procedures available
299- System can be restarted after issues
300
301## 📚 API Reference
302
303### Message Types
304
305**Discovery Messages:**
306- `discover` - Controller requests turtle discovery
307- `mining_turtle_available` - Mining turtle responds to discovery
308- `chunky_turtle_available` - Chunky turtle responds to discovery
309
310**Control Messages:**
311- `start_mining` - Start mining operation
312- `start_chunky` - Start chunky turtle pairing
313- `pause_operation` - Pause current operation
314- `resume_operation` - Resume paused operation
315- `stop_operation` - Stop current operation
316
317**Status Messages:**
318- `status_request` - Request status update
319- `status_update` - Send status information
320- `operation_complete` - Operation finished
321- `operation_error` - Operation failed
322
323**Chunky Messages:**
324- `move` - Move chunky turtle to position
325- `chunk_load` - Send chunk loading signal
326- `chunky_ready` - Chunky turtle ready confirmation
327
328## 🆘 Support
329
330If you encounter issues:
3311. Check this guide first
3322. Verify all files are properly installed
3333. Test with simple parameters first
3344. Check turtle fuel and inventory space
3355. Ensure proper turtle placement and network connectivity
3366. Enable debug mode for detailed logging
337
338## 📝 Version History
339
340**v2.0 (2024-12-19)**
341- Complete rewrite with advanced wireless communication
342- Enhanced error handling and recovery
343- Real-time monitoring and control
344- Improved chunky turtle following behavior
345- Multi-protocol communication support
346
347**v1.0 (Original tClear)**
348- Basic mining functionality
349- Simple chunky turtle pairing
350- Limited wireless communication
351
352---
353
354**Need help?** Check the troubleshooting section or enable debug mode for detailed logging.
355