p5.serialport
Version:
Library for serial port and p5.js
636 lines (255 loc) • 13.1 kB
HTML
<html lang="en">
<head>
<meta charset="utf-8">
<title>JSDoc: Home</title>
<script src="scripts/prettify/prettify.js"> </script>
<script src="scripts/prettify/lang-css.js"> </script>
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
<link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
</head>
<body>
<div id="main">
<h1 class="page-title">Home</h1>
<h3> </h3>
<section>
<article><h1>p5.serialport</h1>
<h2>About</h2>
<p>p5.serialport is a <a href="https://p5js.org/">p5.js</a> library that enables communication between your p5.js sketch and Arduino microcontroller (or another serial enabled device).</p>
<p>p5.serialport was created in 2015 at <a href="https://www.nyu.edu/">New York University</a>'s <a href="https://tisch.nyu.edu/itp">Interactive Telecommunications Program</a> by <a href="https://github.com/vanevery/">Shawn van Every</a>, <a href="https://github.com/kaganjd">Jen Kagan</a>, and <a href="https://github.com/tigoe">Tom Igoe</a>.</p>
<h2>What does it do?</h2>
<p>p5.serialport more or less clones the <a href="https://processing.org/reference/libraries/serial/index.html">Processing Serial Library API</a>. As JavaScript in a browser can not interact directly with a serial port, this library solves this.</p>
<p>p5.serialport comes in two flavors; one is a simple app, this is good for all skill levels and is the easiest to use; another one is Node.js based WebSocket server, this is for more skilled advanced users or someone who needs heavy customization.</p>
<h2>p5.serial App</h2>
<p>To begin download and run a release of p5.serialcontrol, available at https://github.com/p5-serial/p5.serialcontrol/releases. This application incorporates p5.serialserver in a GUI application for MacOS and Windows.</p>
<p>Once you have the application launched load one of the <a href="#examples">examples</a> in your browser to see it in action.</p>
<ul>
<li>You'll likely have to change the name of the serial port in the examples to the one your Arduino is using.</li>
</ul>
<h1>p5.serial Node.js</h1>
<p>To Use:</p>
<p>Connect an Arduino or other serial device to your computuer.</p>
<p>Clone or download this repo and install the dependencies with: <code>npm install</code> and start the server with: <code>node startserver.js</code></p>
<p>Alternatively, you can install the server globally via npm with <code>sudo npm install -g p5.serialserver</code> and then run it with <code>p5serial</code> or locally with <code>npm install p5.serialserver</code> and run it from the node_modules directory with <code>node startserver.js</code></p>
<p>Then load one of the <a href="#examples">examples</a> in your browser to see it in action.</p>
<ul>
<li>You'll likely have to change the name of the serial port in the examples to the one your Arduino is using.</li>
</ul>
<h2>Getting Started</h2>
<p>After running either the <a href="https://github.com/p5-serial/p5.serialcontrol/releases">p5.serialcontrol application</a> or p5.serialserver, you need to include the client side library in your html file. You can download the <a href="https://github.com/p5-serial/p5.serialport/blob/master/lib/p5.serialport.js">p5.serialport.js client library</a> and include this as a script tag as below:</p>
<p><code><script language="javascript" type="text/javascript" src="p5.serialport.js"></code></p>
<p>or, you can use a CDN link available via <a href="https://www.jsdelivr.com/">jsdelivr</a>:</p>
<p><code><script language="javascript" type="text/javascript" src="https://cdn.jsdelivr.net/npm/p5.serialserver@0.0.28/lib/p5.serialport.js"></script></code></p>
<h2><a href="https://p5-serial.github.io/">API</a></h2>
<h2>Examples</h2>
<ul>
<li><a href="/examples/basics/">Basic example</a></li>
<li><a href="/examples/basics-cdn/">Basic example with CDN link</a></li>
<li><a href="/examples/echo/">Echo example</a></li>
<li><a href="/examples/echo2/">Echo with serial options example</a></li>
<li><a href="/examples/makePortMenu/">Make port menu example</a></li>
<li><a href="/examples/readAndAnimate/">Read and animate example</a></li>
<li><a href="/examples/readCount/">Read count example</a></li>
<li><a href="/examples/twoArduinos/">Two Arduinos example</a></li>
<li><a href="/examples/twoArduinosArray/">Two Arduinos array example</a></li>
<li><a href="/examples/writeExample/">Write example</a></li>
</ul>
<h3>Basic Example</h3>
<pre class="prettyprint source lang-javascript"><code>let serial;
function setup() {
// Instantiate our SerialPort object
serial = new p5.SerialPort();
// Let's list the ports available
let portlist = serial.list();
// Assuming our Arduino is connected, let's open the connection to it
// Change this to the name of your arduino's serial port
serial.open("/dev/cu.usbmodem1421");
// Register some callbacks
// When we connect to the underlying server
serial.on('connected', serverConnected);
// When we get a list of serial ports that are available
serial.on('list', gotList);
// When we some data from the serial port
serial.on('data', gotData);
// When or if we get an error
serial.on('error', gotError);
// When our serial port is opened and ready for read/write
serial.on('open', gotOpen);
}
// We are connected and ready to go
function serverConnected() {
print("We are connected!");
}
// Got the list of ports
function gotList(thelist) {
// theList is an array of their names
for (let i = 0; i < thelist.length; i++) {
// Display in the console
print(i + " " + thelist[i]);
}
}
// Connected to our serial device
function gotOpen() {
print("Serial Port is open!");
}
// Ut oh, here is an error, let's log it
function gotError(theerror) {
print(theerror);
}
// There is data available to work with from the serial port
function gotData() {
let currentString = serial.readStringUntil("\r\n");
console.log(currentString);
}
// Methods available
// serial.read() returns a single byte of data (first in the buffer)
// serial.readChar() returns a single char 'A', 'a'
// serial.readBytes() returns all of the data available as an array of bytes
// serial.readBytesUntil('\n') returns all of the data available until a '\n' (line break) is encountered
// serial.readString() retunrs all of the data available as a string
// serial.readStringUntil('\n') returns all of the data available as a tring until a (line break) is encountered
// serial.last() returns the last byte of data from the buffer
// serial.lastChar() returns the last byte of data from the buffer as a char
// serial.clear() clears the underlying serial buffer
// serial.available() returns the number of bytes available in the buffer
function draw() {
// Polling method
/*
if (serial.available() > 0) {
let data = serial.read();
ellipse(50,50,data,data);
}
*/
}
</code></pre>
<h2>Documentation</h2>
<p>To generate documentation, install jsdoc (<code>npm install -g jsdoc</code>) and run
<code>npm run doc</code></p></article>
</section>
<section>
<header>
<h2>classes/Client.js</h2>
</header>
<article>
<div class="container-overview">
<div class="description"><p>Client object that gets created when new web socket client connects to server. Maintains SerialPort objects that the client subscribes to.</p></div>
<dl class="details">
<dt class="tag-author">Author:</dt>
<dd class="tag-author">
<ul>
<li>Shawn Van Every</li>
<li>Jiwon Shin</li>
</ul>
</dd>
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="classes_Client.js.html">classes/Client.js</a>, <a href="classes_Client.js.html#line1">line 1</a>
</li></ul></dd>
</dl>
</div>
<h3 class="subsection-title">Requires</h3>
<ul>
<li>module:NPM:serialport</li>
<li>module:NPM:ws</li>
<li>module:classes/SerialPort.js:SerialPort</li>
</ul>
</article>
</section>
<section>
<header>
<h2>classes/SerialPort.js</h2>
</header>
<article>
<div class="container-overview">
<div class="description"><p>SerialPort class that gets created when new serial port is opened. Maintains list of connected Client objects to forward data received from the serial port.</p></div>
<dl class="details">
<dt class="tag-author">Author:</dt>
<dd class="tag-author">
<ul>
<li>Shawn Van Every</li>
<li>Jiwon Shin</li>
</ul>
</dd>
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="classes_SerialPort.js.html">classes/SerialPort.js</a>, <a href="classes_SerialPort.js.html#line1">line 1</a>
</li></ul></dd>
</dl>
</div>
<h3 class="subsection-title">Requires</h3>
<ul>
<li>module:NPM:serialport</li>
</ul>
</article>
</section>
<section>
<header>
<h2>p5.serialserver.js</h2>
</header>
<article>
<div class="container-overview">
<div class="description"><p>Sets up web socket server and handles client connections by creating and deleting Client objects and SerialPort objects</p></div>
<dl class="details">
<dt class="tag-author">Author:</dt>
<dd class="tag-author">
<ul>
<li>Shawn Van Every</li>
<li>Jiwon Shin</li>
</ul>
</dd>
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="p5.serialserver.js.html">p5.serialserver.js</a>, <a href="p5.serialserver.js.html#line1">line 1</a>
</li></ul></dd>
</dl>
</div>
<h3 class="subsection-title">Requires</h3>
<ul>
<li>module:classes/Client.js:Client</li>
<li>module:classes/SerialPort.js:SerialPort</li>
<li>module:NPM:ws</li>
</ul>
</article>
</section>
<section>
<header>
<h2>startserver.js</h2>
</header>
<article>
<div class="container-overview">
<div class="description"><p>start p5.serialserver by calling start() function in <a href="p5.serialserver.js.html"><code>p5.serialserver.js</code></a></p></div>
<dl class="details">
<dt class="tag-author">Author:</dt>
<dd class="tag-author">
<ul>
<li>Shawn Van Every</li>
<li>Jiwon Shin</li>
</ul>
</dd>
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="startserver.js.html">startserver.js</a>, <a href="startserver.js.html#line3">line 3</a>
</li></ul></dd>
</dl>
</div>
<h3 class="subsection-title">Requires</h3>
<ul>
<li>module:p5.serialserver.js</li>
</ul>
</article>
</section>
</div>
<nav>
<h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="Client.html">Client</a></li><li><a href="SerialPort.html">SerialPort</a></li></ul><h3>Events</h3><ul><li><a href="Client.html#event:message">message</a></li></ul><h3>Global</h3><ul><li><a href="global.html#clients">clients</a></li><li><a href="global.html#LOGGING">LOGGING</a></li><li><a href="global.html#logit">logit</a></li><li><a href="global.html#serialPorts">serialPorts</a></li><li><a href="global.html#serialPortsList">serialPortsList</a></li><li><a href="global.html#start">start</a></li><li><a href="global.html#stop">stop</a></li><li><a href="global.html#wss">wss</a></li></ul>
</nav>
<br class="clear">
<footer>
Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.3</a> on Sun Jul 17 2022 21:38:31 GMT-0400 (Chile Standard Time)
</footer>
<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>