3.3. CNCShieldServer Arduino Sketch

This sketch can generate basic motion for three stepper motors from ASCII commands sent from a host. The following documentation was extracted from the CNCShieldServer sample sketch and highlights particular functions, variables, and classes within the code.

The basic sketch includes a simple command-line Python script to show host-side motion scripting. For a more versatile host-side interface, see the CncShieldGUI Example.

3.3.1. Top-Level Functions

void CNCShieldServer_setup(void)

Standard Arduino initialization function to configure the system.

void CNCShieldServer_loop(void)

Standard Arduino polling function to handle all I/O and periodic processing. This loop should never be allowed to stall or block so that all tasks can be constantly serviced.

void stepper_output_interrupt(void)

Interrupt handler to update all the stepper motor channels. Note that this is called from a timer interrupt context, so it should take as little time as feasible and cannot use serial I/O (i.e. no debugging messages).

3.3.2. Global Values

CncStepper x_axis(X_AXIS_STEP_PIN, X_AXIS_DIR_PIN)

Control objects for the stepper channels. The declaration statically initializes the global state objects for the channels. Note that this does not initialize the hardware; that is performed in setup().

CncStepper y_axis(Y_AXIS_STEP_PIN, Y_AXIS_DIR_PIN)
CncStepper z_axis(Z_AXIS_STEP_PIN, Z_AXIS_DIR_PIN)

3.3.3. ASCII Messaging Protocol

static void cncsrv_parse_input_message(int argc, char *argv[])

Process an input message. Unrecognized commands are silently ignored. argc - number of argument tokens argv - array of pointers to strings, one per token

static void cncsrv_hardware_input_poll(void)

Polling function to read and send specific input values at periodic intervals.

static void cncsrv_serial_input_poll(void)

Polling function to process messages arriving over the serial port. Each iteration through this polling function processes at most one character. It records the input message line into a buffer while simultaneously dividing it into ‘tokens’ delimited by whitespace. Each token is a string of non-whitespace characters, and might represent either a symbol or an integer. Once a message is complete, parse_input_message() is called.

3.3.4. CncStepper Step Generator Class

class CncStepper

An instance of this class manages generation of step and direction signals for one stepper motor.

Public Functions

CncStepper(uint8_t step_pin, uint8_t dir_pin)

Main constructor. The arguments are the pin numbers for the step and direction outputs. Note: this does not initialize the underlying hardware.

void pollForInterval(unsigned long interval)

Main polling function to be called as often as possible. This may be called from a timer interrupt. The interval argument is the duration in microseconds since the last call.

void incrementTarget(long offset)

Add a signed offset to the target position. The units are dimensionless ‘steps’. If using a microstepping driver, these may be less than a physical motor step.

void setTarget(long position)

Set the absolute target position.

long currentPosition(void)

Return the current position in dimensionless ‘steps’.

void setSpeed(int speed)

Set a constant speed in steps/second. Note that the value must be non-zero and positive. The maximum rate available is a function of the polling rate.

Private Members

uint8_t step_pin

the I/O pins for this channel designated using the Arduino convention

uint8_t dir_pin
long target

the target position in dimensionless step counts

unsigned long step_interval

the interval in microseconds between steps

long position

the current position in dimensionless step counts

unsigned long elapsed

the time elapsed in microseconds since the last step occurred

3.3.5. Sample Python Client for CNCShieldServer

The CNCShieldServer sketch includes a sample Python script to send motion commands to the server running on an Arduino. The following is the documentation extracted from the docstrings in the file.

test_client.py : sample code in Python to communicate with an Arduino running CNC_Shield_Server

Copyright (c) 2015, Garth Zeglin. All rights reserved. Licensed under the terms of the BSD 3-clause license.

class CNCShieldServer.test_client.CncShieldClient(port=None, verbose=False, debug=False, **kwargs)[source]

Class to manage a connection to a CNC_Shield_Server running on a serial-connected Arduino.

  • port – the name of the serial port device
  • verbose – flag to increase console output
  • debug – flag to print raw inputs on sconsole
  • kwargs – collect any unused keyword arguments

Shut down the serial connection to the Arduino, after which this object may no longer be used.


Issue a command to enable or disable the stepper motor drivers.


Issue a command to move to a [x, y, z] absolute position (specified in microsteps) and wait until completion.

Parameters:position – a list or tuple with at least three elements

Issue a status query and wait until an ‘awake’ status has been received.