Line-us is a small internet connected robot drawing arm. It copies your movements in real time and draws with a real pen on paper.
Line-us can be controlled using a simple API, either TCP Sockets or Websockets. The commands are a subset of GCode, loosely based on the RepRap spec. The supported GCode set is described in the GCode Specification Document but the primary command used for drawing is the G01 (interpolated move) command.
Be sure to check out the Line-us Drawing Area Diagram which will tell you all you need to know about the co-ordinate system that Line-us uses and the shape of the drawing space.
The simplest way to get started is to try one of the examples below.
- Simple Python Example
- Simple Processing Example
- Simple Node Example created by pandrr
- Line-us JS Kit created by funwithtriangles
- Simple C Example created by Paul Haeberli
- C# Unity Example created by soylentgraham
- Java Generative app by @fiskdebug
- Simple Dart Example
- Simple SVG Plotter for Line-us by Michael Zöllner
- Making a connection
- Sending GCode
- Responses from Line-us
- Timing
- Co-ordinate System
- CAUTION for firmware 1.0.1 and lower
There are two simple examples for python. Source code for a very simple example using the TCP Sockets API can be downloaded from here. The example works with Python 2.7 and Python 3, but Python 3 is preferred. There is also Source code for a straightforward prot of the TCP example to use the websockets API that can be downloaded here. For the sake of clarity the Websockets example tries to sidestep the use of asyncio by wrapping each of the async functions.
Source code for a very simple example can be downloaded from here. The example works with with Processing 3.3.7 (Java) - just copy and paste into your Processing window.
Pandrr has ported our Python example to Node! - check out his GitHub here
Write commands in JavaScript and preview the drawing in your browser before sending to Line-us! Created by Alex Kempton, check out his Github here
Source code for a simple example in C created by Paul Haberli can be downloaded from here. The code complies on MACOS using gcc but should be fairly portable. A Makefile is also included so if you have gcc in your path, just type 'make'
C (wrapped in unity for now) implementation of the protocol for Line-us created by solentygraham, check out his GitHub here
Very nice Java app available as source or an installable package for Mac on @fiskfamilij's GitHub
Source code for a very simple example can be downloaded from here. You'll need Dart installed.
Great little app to plot your SVG files directly to Line-us. Available as installers for Mac and Windows or source with instructions on Michael's GitHub.
If you're thinking of writing some Javascript you should definitely check out this library as it will make your life much easier. It handles connection, queueing and all of the things you really don't want to do yourself. Works in the browser as well as with Node. Everything you need is at Beardicus's GitHub
A library created by fxmorin to allow you to use your Line-us with PHP. Available at fxmorin's GitHub
As of firmware 3.0.0 Line-us offers a webscokets API as well as the original TCP Sockets API. All of the commands and responses are the same across both of the APIs, but there are a small number of commands that are not avaialble in the websockets API for security reasons (for example M587 to set WiFi details). Details are in the GCode Specification Document.
The default name for Line-us is line-us, although it can be changed using the M550 Gcode command or using the App. Line-us supports mDNS (Bonjour) so by default the hostname will be line-us.local. On a successful connection Line-us will respond with a hello message followed by KEY:value pairs for VERSION (firmware version number) NAME (the name of the Line-us) and SERIAL (the serial number of the Line-us). For example hello VERSION:"3.2.0 Nov 17 2019 17:54:57" NAME:line-us SERIAL:123456
Line-us listens on TCP port 1337 and the connection to Line-us can be tested with a telnet client by using the command telnet line-us.local 1337. On connection you will receive the hello message, which (like all messages from Line-us) is terminated with \r\n\0. In firmware < 3.0.0 it was very important that the full hello message was read from the socket including the \0 before any commands were sent. Firmware 3.0.0 or later has an improved TCP stack that means that this is no longer critical. It is still best to read the message though.
The websockets URL for your Line-us (assuming you're using the default name) is ws://line-us.local. Note that it is not a secure (wss:) websocket - unfortunately Line-us's tiny brain isn't quite up to running SSL. On connection you will receive the hello message and once you've received it you can start to send GCode. A simple way to experiment with the websockets API is to use Firecamp - just connect and send one GCode per message.
GCode commands are a command followed by a zero or more parameters separated by white space. Parameters are a single letter followed immediately by the value. The GCode Specification Document has details of all of the available GCodes, but a simepl example would be G01 X1000 Y0 Z1000 to move to point (1000, 0) with the pen up. Where necessary the values can be enclosed in double quotes " for example M587 Smy-ssid P"password with spaces" if you have spaces in your WiFi password. For TCP Sockets connections GCode commands must be terminated by one of, or a combination of \r, \n, and \0. Websockets connections do not require any terminators in the messages.
Each GCode response will result in a response message from Line-us, which will start with either ok indicating success, or error indicating an error and is followed by zero or more KEY:value pairs as described in the GCode Specification Document. For TCP Sockets the response message is terminated with \r\n\0. In firmware < 3.0.0 it was essential that the full response message was read from the socket including the \0 before the next command was sent. This is no longer the case with firmware 3.0.0 or later although it is still advisable to read the messages. Fow websockets the respnse will be received in a text messsage.
If a GCode command that moves the arm is sent to Line-us while the arm is still in motion the command will be accepted, but the response message will not be sent until the prior movement has completed. This means that the sender will remain in sync with the arm (at most there will be one outstanding command).
Line-us GCode commands use 'machine co-ordinates'. The origin point (0, 0) for the co-ordinate system is at the centre point of the servo shafts, and GCode commands use drawing units (100 drawing units is approximately 5mm). The home point for the arm is (1000, 1000). The z axis is the pen height; 0 is down and 1000 is up. The shape if the drawing area is not rectangular. See the Line-us Drawing Area Diagram for details. If a GCode for a movement outside of the drawing is sent Line-us will move to something approximating the closest it can get to that point while still remaining within the drawing area and lift the pen.
It should not be possible to send a GCode that overstretches the arm, or causes it to hit the body of Line-us. However, in firmware 1.0.1 and lower there is an area where the pen screw can come into contact with the body. For y positions < 0 the x coordinate should be limited to x >= 700 by your software as firmware 1.0.1 and lower allow x >= 500 in this zone. This will has now been fixed so please update to the latest firmware.
