Documentation | Usage Guide

Machine Week Group Project - 2-Axis CNC Plotter

This week our team focused on building a complete small CNC plotting machine from scratch: mechanics, electronics, firmware, and testing.

Our goal was not only to make it move, but to make it reproducible and clearly documented so another team can rebuild it.

We used a Raspberry Pi Pico (RP2040) as the controller, two stepper motors with TMC2208 drivers for motion, and one servo motor for pen up/down.

Firmware is written in MicroPython and controlled over USB serial commands.

> Attribution: This firmware is a remix of the PicoNC idea and workflow. We adapted the base concept for our machine with CoreXY support, pen-servo control, and a practical command set for drawing.

1) Project Intent and Scope

For Machine Week, we wanted a compact plotting machine that can:

• draw lines and shapes reliably,
• support pen lift and pen drop,
• accept simple serial commands from a host computer,
• be easy to calibrate mechanically and in software.

2) Machine Building and Assembly

Build Source and Preparation

We followed the Blot assembly workflow and adapted it to our available lab hardware:

• Assembly guide: Blot Assembly Guide
• Mechanical files: Blot drawing-thing-v4
• We 3D printed the required parts and designed custom spacers because standard aluminum spacers were not available in the lab.

Figure 1. Used parts prepared before assembly.

Carriage Assembly

We started by assembling the carriage using:

• 4 x M5x25 Button Cap Screw
• 8 x M5x35 Button Cap Screw
• 8 x 625zz V-Wheel
• 8 x 5x16x5 mm flanged bearing
• 4 x 6 mm x 8 mm OD x M5 spacer
• 12 x M5 Nut
• 4 x 6 mm M5 eccentric spacer
• 4 x 1 mm x 10 mm OD x M5 spacer
• 1 x Carriage
• 1 x Carriage Plate

Detailed assembly sequence:

1. Place the printed carriage body on a flat table and pre-sort long screws, spacers, eccentric spacers, and wheels.
2. Press the flanged bearings into the wheel positions and verify each wheel rotates freely before mounting.
3. Mount the first two wheels diagonally on the carriage plate, then add the opposite pair to keep the plate balanced during tightening.
4. Install the fixed spacers on one side and eccentric spacers on the adjustable side so wheel preload can be tuned later.
5. Insert M5 screws through the wheel stack (screw -> wheel/bearing -> spacer/eccentric -> printed part -> nut) and keep nuts slightly loose.
6. Tighten in a cross pattern, then rotate eccentric spacers until all wheels touch the rail profile without binding.
7. Final check: carriage should slide smoothly with no rattle and no hard points.

Figure 2. Carriage plate assembly with wheel hardware layout.

Figure 3. Bottom side of the carriage after wheel installation.

Figure 4. Top side of the carriage showing final wheel alignment.

Printed Rail and Tool Holder

For the printed rail assembly we used:

• 1 x M5x25 Button Cap Screw
• 1 x M5 Nut
• 1 x 1 mm x 10 mm OD x M5 spacer
• 1 x Printed Rail
• 2 x 5x16x5 mm flanged bearing
• 1 x Servo (25 mm cable) + arm

Detailed assembly sequence:

1. Insert the two flanged bearings into the printed rail pocket, matching the orientation visible in the photo.
2. Pass the M5 screw through the rail and bearing stack with the 1 mm spacer where needed to avoid side rubbing.
3. Secure with the M5 nut but keep a small clearance so the bearing can rotate freely.
4. Dry-fit the servo in its slot and verify the horn side aligns with the pen-link side before final fastening.
5. Route the servo cable toward the rear side of the machine to keep it away from moving belts.

Figure 5. Printed rail with bearing installed inside the housing.

Then we assembled the tool holder using:

• 3 x M5x25 Button Cap Screw
• 4 x M5 Nut
• 1 x M5x20 knurled cylinder head
• 1 x Tool Head
• 1 x 6 mm M5 eccentric spacer
• 3 x 625zz V-Wheel

Detailed assembly sequence:

1. Build the 3-wheel triangular arrangement first (two supporting wheels and one adjustable wheel).
2. Use the eccentric spacer on the adjustable wheel so the grip on the rail can be tuned.
3. Install the knurled M5x20 pen clamp screw through the tool-head body and test with a real pen during assembly.
4. Tighten the wheel hardware until the holder rolls smoothly on the printed rail with minimal side play.
5. Verify pen axis is vertical and the pen can move up/down without touching wheel hardware.

Figure 6. Front view of tool holder with three-wheel arrangement and pen test fit.

Figure 7. Side view of tool holder showing pen clamp and wheel stack.

Frame, Feet, and Belts

We cut two aluminum extrusions to 25 cm:

Figure 8. Aluminum extrusion cutting process (view 1).

Figure 9. Aluminum extrusion cutting process (view 2).

After checking carriage travel on the extrusions, we assembled the feet with:

• 2 x Timing Belt Pulley
• 8 x M3x10 Button Cap Screw
• 2 x Motor Leg
• 2 x NEMA17 Stepper Motors (42 x 42 x 38 mm)

We used 3 T-nuts per leg to fix the motor feet.

Detailed assembly sequence:

1. Slide T-nuts into the side channels of each 25 cm extrusion before closing both ends.
2. Align each printed leg square to the extrusion and lightly tighten screws first.
3. Mount each stepper on the leg and install pulley on motor shaft; keep pulley height aligned with belt path.
4. Re-check frame squareness by measuring diagonals, then perform final tightening.
5. Mount the cross rail/carriage assembly and confirm full travel by hand.

Figure 10. Inserting and positioning T-nuts in extrusion channels.

Figure 11. Frame with feet and carriage mounted for travel checks.

For belt routing, we created a loop through the belt fastener, routed through carriage and pulleys, then returned to the fastener and tensioned.

Detailed belt routing and tensioning:

1. Make the first belt loop and lock it into the carriage-side belt fastener.
2. Route belt around the first pulley, through the carriage path, and around the opposite side pulley as shown.
3. Return belt end back to the fastener and create the second loop.
4. Keep both belt segments parallel and untwisted in the central crossing area.
5. Apply tension gradually while moving carriage by hand to detect tight spots.
6. Final tension target: no visible slack, smooth travel end-to-end, and no audible skipping when moved quickly by hand.

Figure 12. Belt routing through pulley and carriage path.

Figure 13. Top view of belt crossing and alignment.

Figure 14. Overall machine assembly after belt installation.

Servo as Z-Like Pen Axis

The servo motor on the tool holder provides pen up / pen down behavior (Z-like action for drawing).

Figure 15. Pen down position for drawing.

Figure 16. Pen up position for travel moves.

Mechanical Lessons Learned

• Validate free movement first with motors unpowered.
• Belt tension is a calibration parameter, not a one-time step.
• Small mounting offsets show up clearly in drawn diagonals.
• Mechanical alignment quality directly affects software tuning effort.

3) Electronics and Wiring

Controller and drivers:

• Raspberry Pi Pico (RP2040)
• 2x TMC2208 stepper drivers
• 1x servo for pen lift

Pin Mapping

Tested working in our setup:

• stepper channel on GP8/GP9,
• stepper channel on GP12/GP13,
• servo on GP27.

Electrical Notes

• Common ground between Pico, drivers, and servo is mandatory.
• Motor current on TMC2208 must be set conservatively first, then tuned.
• Servo line should be clean; noisy power can cause jitter.

4) Firmware and Software Documentation

Firmware runs on MicroPython and exposes a line-based serial protocol over USB CDC.

Core Features

• Two-axis stepper control with synchronous line movement.
• Optional COREXY transform (A = X + Y, B = X - Y).
• Pen lift/lower through servo:
• ANGLE mode for normal positional servo,
• CR mode for continuous-rotation servo.
• Runtime tuning commands for speed and servo behavior.
• Blocking movement model for predictable path execution.

Main Configuration Parameters

# Servo
SERVO_MODE = "CR"        # "ANGLE" or "CR"
SWAP_PEN = True
PEN_UP_ANGLE = 30
PEN_DOWN_ANGLE = 120
SERVO_STOP_US = 1500
PEN_UP_US = 1400
PEN_DOWN_US = 1600
PEN_UP_MS = 220
PEN_DOWN_MS = 220

# Kinematics
COREXY = True
SWAP_XY = True
MOTOR_A_SIGN = 1
MOTOR_B_SIGN = 1

# Motion speed
DEFAULT_INTERVAL = 1200  # microseconds, lower is faster

Kinematics Behavior

• In Cartesian mode, command X and Y directly map to physical axes.
• In CoreXY mode:
• motor A steps = X + Y
• motor B steps = X - Y

If axis behavior looks wrong:

• diagonal instead of straight: enable/verify COREXY,
• swapped axes: toggle SWAP_XY,
• wrong direction: invert MOTOR_A_SIGN / MOTOR_B_SIGN.

Motion Model

Motion is intentionally blocking.

Each command executes to completion before next command is processed.

Why we kept it this way:

• easier to reason about during machine bring-up,
• more deterministic timing on microcontroller,
• stable behavior with simple serial senders (Thonny/Web Serial).

5) Serial Command Protocol

Commands are case-insensitive, one line each, ending with newline.

• Success response: OK ...
• Error response: ERR ...
• Comment lines: start with #

Motion Commands

Pen / Servo Commands

Example Session

PLOTTER READY
PENUP
OK PEN_UP
MOVE X500 Y500
OK MOVE X=500 Y=500
PENDOWN
OK PEN_DOWN
X1000
OK X 1000
Y-500
OK Y -500
PENUP
OK PEN_UP

6) Software Workflow (Host Side)

Our workflow for testing and drawing:

1. Flash latest MicroPython to Pico.
2. Upload firmware as main.py.
3. Open serial console (Thonny or Web Serial terminal).
4. Run manual movement tests:

• PENUP
• X100, Y100, X-100, Y-100
• MOVE X200 Y200

motor tests

Figure 20. Carriage movement test driven from the software command interface.

1. Tune:

• speed with SPEED,
• pen behavior with PENUP_ / PENDOWN_.

1. Send drawing path commands.

For reliable start-up, we always:

• home manually to a known corner,
• issue PENUP first,
• test one short diagonal before full drawing.

7) Calibration, Validation, and Results

What We Calibrated

• Axis direction and axis mapping.
• CoreXY enable/disable according to movement behavior.
• Step interval for smooth motion without skipping.
• Servo pulse width and hold times for clean pen transitions.

Validation Method

• Drew straight horizontal/vertical lines to verify axis orthogonality.
• Drew diagonals in both directions to verify synchronization.
• Repeated the same square pattern multiple times to check consistency.

Observed Results

• Motion is stable at conservative speed settings.
• Diagonal quality improves significantly after belt and CoreXY tuning.
• Pen lift reliability depends mostly on correct CR neutral and hold duration.

Calibartion test

Figure 19. Assembly-stage movement test after mounting frame, feet, and carriage.

8) Troubleshooting Guide

Pen motion reversed (up/down swapped): toggle SWAP_PEN.

X produces diagonal movement: enable COREXY.

X and Y appear exchanged: set SWAP_XY = True.

One motor direction wrong: invert MOTOR_A_SIGN or MOTOR_B_SIGN.

Motors stall at high speed: increase DEFAULT_INTERVAL (slower), then retune.

Servo jitters: verify power stability and adjust pulse values.

CR servo drifts at stop: tune SERVO_STOP_US around neutral (for example 1490-1520).

9) What We Would Improve Next

• Add hard or soft homing routine.
• Add endstop support and coordinate tracking.
• Add simple G-code subset parser.
• Add acceleration profile (instead of constant pulse interval).

This would move the project from a robust weekly prototype to a more complete production-style machine controller.

10) Usage

This section links to the interactive usage/control pages for the HAAC plotter workflow:

• Usage guide section is available below on this same page.
• Control dashboard: ./plotter/basic-control.html
• API page: ./plotter/api.html
• Full work page: ./plotter/work-page.html

Sample usage

Figure 17. Usage site walkthrough video.

11) Video

Figure 17. Machine Week demo video file preview.

12) Group Reflection

Machine Week forced us to connect mechanical reality and software logic directly.

We observed that many apparent "software bugs" in machine projects are actually system-level interactions between mechanics, wiring, and timing assumptions.

The strongest outcome was getting clean and repeatable drawing only after tuning all subsystems together.

Our main takeaway is that documentation is part of the machine itself: if calibration and decisions are not written clearly, the machine is not truly reproducible.

Usage Guide

Project A Setup

Step 1: Open PyCharm

1. Launch PyCharm.
2. Click New Project.
3. If needed, download PyCharm from JetBrains.

Step 2: Create Project

1. Name it something like NetworkingProject.
2. Click Create.
3. Wait for the project to load.

PyCharm new project window.

Step 3: Create Python File

1. Click the + sign at the top of the left panel.
2. Select New Python File.
3. Name it server.

This creates server.py.

Step 4: The Code

Paste the following code into server.py:

from http.server import BaseHTTPRequestHandler, HTTPServer

class MyHandler(BaseHTTPRequestHandler):
    def do_GET(self):
        message = self.path[1:]  # remove "/"
        print("Received message from iPhone:", message)
        self.send_response(200)
        self.end_headers()
        self.wfile.write(b"Message received!")

server = HTTPServer(("0.0.0.0", 8000), MyHandler)
print("Server running...")
server.serve_forever()

The server code opened in PyCharm and running successfully.

Step 5: Run the Code

1. Right-click inside the file.
2. Click Run 'server'.
3. Or click the green arrow button.

You should see Server running... at the bottom.

Step 6: Get Your IP Address

1. Open the PyCharm terminal or normal Command Prompt.
2. Type ipconfig.
3. Find the IPv4 address, for example 192.168.X.X.

Finding the IPv4 address using ipconfig.

Project B Setup

1. On the iPhone, open Safari.
2. Type the local server address in this format:

http://192.168.x.x:8000/HelloFromiPhone

Then enter the website.

The iPhone sending a message by entering the server URL in Safari.

The browser confirms that the message was received.

Final Result of One-Way Communication

In the PyCharm console, we could see:

Received message from iPhone: HelloFromiPhone

This confirmed that the system worked successfully.

Console output confirming successful one-way communication.

2-Way Communication System

Instead of just sending a message, we stored messages on the server and allowed both devices to send and receive messages. In this way, the project became a mini chat system.

Step 1: Replace the Code

In PyCharm, replace the previous code with the following:

from http.server import BaseHTTPRequestHandler, HTTPServer
import urllib.parse

messages = []  # shared message list

class MyHandler(BaseHTTPRequestHandler):
    def do_GET(self):
        global messages

        if self.path.startswith("/send"):
            query = urllib.parse.urlparse(self.path).query
            params = urllib.parse.parse_qs(query)

            msg = params.get("msg", [""])[0]
            sender = params.get("sender", ["Unknown"])[0]

            full_msg = f"{sender}: {msg}"
            messages.append(full_msg)
            print(full_msg)

            self.send_response(200)
            self.end_headers()
            self.wfile.write(b"Message sent!")

        elif self.path.startswith("/messages"):
            self.send_response(200)
            self.end_headers()
            response = "\n".join(messages)
            self.wfile.write(response.encode())

        else:
            self.send_response(200)
            self.send_header("Content-type", "text/html")
            self.end_headers()

            html = f"""
            <html>
            <body>
            <h2>Mini Chat</h2>
            <form action=\"/send\">
            Name: <input type=\"text\" name=\"sender\"><br><br>
            Message: <input type=\"text\" name=\"msg\"><br><br>
            <input type=\"submit\" value=\"Send\">
            </form>
            <h3>Messages:</h3>
            <pre id=\"chat\"></pre>
            <script>
            async function loadMessages() {
                let res = await fetch('/messages');
                let text = await res.text();
                document.getElementById('chat').innerText = text;
            }
            setInterval(loadMessages, 1000);
            </script>
            </body>
            </html>
            """
            self.wfile.write(html.encode())

server = HTTPServer(("0.0.0.0", 8000), MyHandler)
print("Chat server running...")
server.serve_forever()

The updated code for the two-way communication system.

Step 2: Run It

Click Run in PyCharm. You should see:

Chat server running...

Step 3: Open on Both Devices

On the computer browser:

http://localhost:8000

On the iPhone in Safari:

http://YOUR_IP:8000

Then send messages between both devices.

Mini Chat Interface

After clicking Send on the phone, the chat interface and message confirmation appeared.

The chat interface opened on the iPhone.

The confirmation page shown after sending a message.

Messages displayed in the browser on the computer.

Server logs showing requests and sent messages.