Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/beardicus/line-us

A library for accessing Line-us drawing robots via Node.js and the browser.
https://github.com/beardicus/line-us

Last synced: about 1 month ago
JSON representation

A library for accessing Line-us drawing robots via Node.js and the browser.

Host: GitHub
URL: https://github.com/beardicus/line-us
Owner: beardicus
License: mit
Created: 2018-12-23T19:54:17.000Z (almost 6 years ago)
Default Branch: main
Last Pushed: 2022-12-04T11:28:10.000Z (about 2 years ago)
Last Synced: 2024-04-14T22:19:12.423Z (8 months ago)
Language: JavaScript
Homepage:
Size: 573 KB
Stars: 27
Watchers: 3
Forks: 1
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE

Awesome Lists containing this project

awesome-plotters - @beardicus/line-us - JavaScript library for controlling the Line-us machine from Node or the browser. (Software / Plotter Control)

README

# @beardicus/line-us

A JavaScript library for controlling the [Line-us](https://line-us.com) drawing robot via its websocket interface. Works in both Node.js and the browser.

## Example

```js
const LineUs = require('@beardicus/line-us')
const bot = new LineUs()

bot.on('connected', async () => {
// draw an 'X'
bot.moveTo({ x: 0, y: 0 })
bot.lineTo({ x: 500, y: 500 })
bot.moveTo({ x: 500, y: 0 })
bot.lineTo({ x: 0, y: 500 })

// wait for home
await bot.home()
console.log(`job's done!`)
})
```

## Contents

- [Installation](#installation)
- [Setup](#setup)
- [Communication](#communication)
- [Movement](#movement)
- [Configuration](#configuration)
- [Events](#events)
- [TODO](#todo)

## Installation

Install via npm:

```shell
$ npm install @beardicus/line-us
```

A prebuilt browser version is also available via the [unpkg](https://unpkg.com/) CDN:

```html

```

## Setup

The code in this section is used to set up and configure a new `LineUs` instance.

### `LineUs = require('@beardicus/line-us')`

Imports the `LineUs` class. If you're using the prebuilt browser version of the library (using a `` tag) you should skip this, as there will already be a global `LineUs` class available.

### `bot = new LineUs({opts})`

Create a `LineUs` instance. Optionally, pass in an object to set options:

```js
{
url: 'ws://line-us.local',
autoConnect: true,
autoStart: true,
concurrency: 3
}
```

**Parameters:** all are optional. The default values are shown above.

- **`url`**: (optional) a string that contains the websocket address to connect to. **Default is `ws://line-us.local`** which is the default name and address of all Line-us machines
- **`autoConnect`**: (optional) a boolean, if true will automatically attempt to connect to the websocket. **Defaults to `true`**
- **`autoStart`**: (optional) a boolean, if true the queue will be started automatically upon connection to the websocket. **Defaults to `true`**. See [Queue Control](#queue-control) for more information on the command queue.
- **`concurrency`**: (optional) a number which controls how many commands are sent to be buffered by the Line-us machine. This setting can improve performance where the network between the sender and Line-us has high latency. Note that higher values will create delays with the `pause()` command, as the Line-us will always execute the buffered commands before pausing. **Defaults to `3`**. This value enables relatively smooth operation on local Wifi networks, but you may want to increase it for poorer connections with more latency.

## Communication

This library uses a websocket connection to communicate with your Line-us machine. The commands in this section control the websocket connection and allow you send messages to your machine.

### `.connect()`

Connects to the Line-us machine's websocket. This is done automatically unless `autoConnect` is set to `false` when creating the `LineUs` instance. Returns a promise that resolves when the connection is established.

### `.disconnect()`

Closes the websocket connection and stops and clears the queue. Returns a promise that resolves when the websocket is closed.

### `.send({cmd})`

Sends a command to the machine, first buffering it in the queue if necessary.

You probably don't want to use this directly, and should instead use the commands listed in the [Movement](#movement) and [Configuration](#configuration) sections to interact with the machine.

**Parameters:** accepts a single object that will be serialized into G-code. For example:

```js
{
g: 'G01',
params: {
x: 1000,
y: 900
}
}
```

- **`g`**: (required) the G-code command
- **`params`**: (optional) an object with any parameters the G-code requires

All G-codes and parameter keys (`x` and `y` in the example above) are forced to uppercase (though the Line-us machine doesn't seem to care). The example above would be serialized into:

```
G01 X1000 Y900
```

**Returns:** all commands sent to the Line-us websocket will return a promise that resolves when we receive a response. The value will be the machine's response parsed into an object such as the following:

```js
{
x: '350',
y: '500',
z: '0'
}
```

The exact data returned depends on the command being responded to.

## Movement

The commands in this section all deal with moving the robot arm. They are all asynchronous and return a promise for the Line-us machine's eventual response. See [Movement Responses](#movement-responses) for more detailed information.

You should be able to draw a masterpiece using just the canvas-style `.moveTo()` and `.lineTo()` commands, but the trio of `.penUp()` `.penDown` and plain `.to()` movements are also available for any situations where they may be more ergonomic to use.

The coordinate system used is different from the Line-us machine's default "machine coordinates". If you look at the [Line-us drawing area diagram](https://github.com/Line-us/Line-us-Programming/blob/master/Documentation/LineUsDrawingArea.pdf), this library places the `{x: 0, y: 0}` origin in the upper left of the area labeled "App drawing area". Positive numbers move to the right and down just like in the browser and the canvas API. The machine's home position in this coordinate system is `{x: 350, y: 0}`. The `z` axis behavior remains the same.

### `.moveTo({xy})`

Moves the arm to the coordinates specified, lifting the pen first if necessary.

**Parameters:** an object with one or both of `x` and `y` coordinates specified:

```js
{
x: 800,
y: 900
}
```