• Stars
    star
    136
  • Rank 267,670 (Top 6 %)
  • Language
    JavaScript
  • License
    GNU General Publi...
  • Created over 8 years ago
  • Updated almost 2 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

a JavaScript library that uses an audio software modem to communicate with an Arduino via a headphone jack

WebJack

Build Status

WebJack is a JavaScript library that uses SoftModem, an Arduino library, to create two-way communication between a browser window and an Arduino. No need to install drivers. Just plug in an audio cable and read/send data from the browser.

picture of an Arduino and a dust sensor held in a hand, with a headphone cable coming out

Try it out in this live demo: https://publiclab.github.io/webjack/examples/

Or in this simple sketch in p5js: https://alpha.editor.p5js.org/jywarren/sketches/rkztwSt8M

And to test without an Arduino, use this YouTube video recording of sensor data: https://www.youtube.com/watch?v=GtJW1Dlt3cg

WebJack was built by @rmeister with input from @jywarren as part of Public Lab's 2016 Google Summer of Code program.

Ask questions and find more tutorials at https://publiclab.org/webjack.

webjack console receiving data


Also see webjack-firmata, which builds on webjack to provide a browser-based hardware interface for firmata.js.

Installation

  1. If not already done, install the SoftModem Arduino library: https://github.com/arms22/SoftModem
  2. Choose an example sketch and upload it to your Arduino.
  3. Now install WebJack with
npm install --save webjack

or

bower install -S webjack 

Requirements

Hardware

An Arduino Uno or any other ATmega328p based board is required. Future support for other controllers is discussed here. In addition, it is strongly recommended to build the circuit (or buy the shield) found at SoftModem.

The Arduino can be connected to a laptop or smartphone with the correct cable, but different laptops and smartphones require different cables. See Hardware, below.

Software

WebJack uses the adapter.js shim for browser interoperability. You have to make sure adapter.js is loaded before webjack.js. Have a look at the demo site in the examples folder.

jQuery is only used for the demo site and not required for WebJack.

Usage

var profile = WebJack.Profiles.SoftModem;
var connection = new WebJack.Connection(profile);

connection.listen(function(data) {
	console.log('received: ' + data);
});

connection.send('some data');

Profiles

Depending on the profile, WebJack uses different frequencies for the FSK modulation.

Profile Parameters Use Case Demo
SoftModem (default) 1225 bit/s, 4900 and 7350 Hz Communication with the SoftModem Arduino library Demo
SoftModemLowFrequencies 1225 bit/s, 2450 and 4900 Hz Reduced crosstalk for long cables Demo
Browser 1225 bit/s, 19600 and 20825 Hz Browser-to-browser transmissions over the air Demo

For the SoftModemLowFrequencies profile, echo cancellation is activated to reduce loopback produced by crosstalk between wires. Due to the echo cancellation some filters are applied that also reduce the upper frequency limit. Therefore you need to add this definitions to the head of your Arduino sketch, to configure SoftModem for lower frequencies:

#define SOFT_MODEM_LOW_FREQ    (2450)
#define SOFT_MODEM_HIGH_FREQ   (4900)

Note: It is recommended to make the cable length as short as possible, before using the non-default profile.

The Browser profile is a planned feature and not working yet. Its purpose is communication between browser tabs on the same or a different device.

Individual Profile Options

You can change profile attributes individually.

profile.raw

By default, WebJack tries to parse received data into strings. To get the raw data stream as array of bytes, set the raw attribute of the profile to true:

var profile = WebJack.Profiles.SoftModem;
profile.raw = true;
var connection = new WebJack.Connection(profile);

profile.baud

The baud-/bitrate. Has to be a factor 44,1kHz and below 1225 bit/s.

profile.freqLow

The frequency of the lower tone, marks a 0 and has to be a multiple of the baudrate.

profile.freqHigh

The frequency of the upper tone, marks a 1 and has to be a multiple of the baudrate.

profile.echoCancellation

Turn on or off echoCancellation. This enables or disables filtering (high-/lowpass) as well.

profile.softmodem

Set to false for transmissions between browser tabs to improve transmission reliability.

Plotting

If you are receiving sensor data, you can plot a graph of incoming values in the plotter example. Test it out even without a sensor, by playing audio from this YouTube video of WebJack-transmitted sensor data out loud into the microphone while viewing the above demo.

plotted data


Hardware

Arduino wiring

Follow this diagram (and the cable pinouts guide below) to connect an audio cable to your Arduino in the right way for your smartphone or laptop:

arduino-diagram.png

Cable pinouts

Most smartphones have a 4-pin combined microphone/stereo headphone port which takes a 3.5mm plug, but there are unfortunately different standards for which plug positions (from tip to sleeve) correspond to which wires, and there's no guarantee that the wires are colored helpfully. The best way to test a cable you're using is to use a multimeter, or to light up an LED using different pin/wire combinations to see what wire corresponds to what pin.

Pin # Position OMTP AV connector AHJ AV connector
1 sleeve Ground Microphone
2 ring Microphone Ground
3 ring Right audio Right audio
4 tip Left audio Left audio
Devices: Samsung,older Sony Ericsson and Nokia HTC, recent Sony and Nokia, Apple

3.5mm to RCA AV cables (to red/white/yellow "TV-style" plugs) vary: see this listing for various pinouts, and note that the wires inside your cable may be labelled with the convention of red:right, white:left, and yellow:video. The ground wires may be wrapped around each of those three wires, which provides shielding from interference.


Troubleshooting

If you have problems setting up the connection, you can file an issue. Please include following information:

  • Hardware: board, circuit/shield, smartphone
  • Software: Arduino sketch, your webbrowser, used WebJack profiles
  • A recording of the received signal. Please use this AudioRecorder.
  • Error messages that occurred

Building

webjack.js is built using a Grunt task from the source files in /src/, and the compiled file is saved to /dist/webjack.js. To build, run grunt build. To watch files for changes, and build whenever they occur, run grunt.

Testing

Assuming tape is installed globally:

npm test

Developers

Help improve Public Lab software!

More Repositories

1

plots2

a collaborative knowledge-exchange platform in Rails; we welcome first-time contributors! 🎈
Ruby
958
star
2

Leaflet.DistortableImage

A Leaflet extension to distort or "rubber sheet" images
JavaScript
270
star
3

mapknitter

Upload your own aerial images, position (rubbersheet) them in a web interface over existing map data, and share via web or composite and export for print.
Ruby
267
star
4

community-toolbox

Tools to understand and welcome people into a contributor community
JavaScript
141
star
5

spectral-workbench

Web-based tools for collecting, analyzing, and sharing data from a DIY spectrometer
Ruby
126
star
6

leaflet-environmental-layers

Collection of different environmental map layers in an easy to use Leaflet library, similar to https://github.com/leaflet-extras/leaflet-providers#leaflet-providers
JavaScript
99
star
7

PublicLab.Editor

A general purpose, JS/Bootstrap UI framework for rich text posting. An author-friendly, minimal, mobile/desktop interface for creating blog-like content, designed for PublicLab.org
JavaScript
79
star
8

spectral-workbench.js

The JavaScript heart of Spectral Workbench; a Public Lab project to record, manipulate, and analyze spectrometric data.
JavaScript
46
star
9

infragram

A minimal core of the Infragram.org project in JavaScript
HTML
44
star
10

simple-data-grapher

Turns CSVs into graphs in a few simple steps; embeds onto other websites!
JavaScript
38
star
11

leaflet-blurred-location

A Leaflet-based interface for selecting a "blurred" or low-resolution location, to preserve privacy
JavaScript
35
star
12

inline-markdown-editor

An inline wysiwyg markdown document editor based on replacing string subsections. WYSIWYG possible via woofmark.
JavaScript
30
star
13

pi-builder

Developing a reproducible build script system for making Raspberry Pi .img files
Ruby
22
star
14

leaflet-multispectral

Multispectral color manipulation and processing (NDVI etc) for Leaflet image overlays with pure JavaScript in Image Sequencer
HTML
22
star
15

plotsbot

A bot for Public Lab
JavaScript
17
star
16

papercraft-spectrometer

An introductory papercraft spectrometry kit
13
star
17

sky-camera

Public Lab's Android Aerial Acquisition App
Java
12
star
18

spectrometer3

Public Lab's open source Desktop Spectrometry Kit
11
star
19

leaflet-blurred-location-display

A library to display points which have been "blurred" for privacy with leaflet-blurred-location
JavaScript
11
star
20

SmART-Form

A community science effort to measure formaldehyde in the home environment
Java
9
star
21

webjack-firmata

A wrapper for WebJack to use as transport layer for firmata.js, for firmata access to an Arduino from a web browser.
JavaScript
9
star
22

mapmill

A Hot-or-Not styled crowdsourcing engine for sorting raw map imagery
HTML
8
star
23

colorimetry

A web-based colorimetry toolkit, using Image Sequencer
JavaScript
8
star
24

infragram-ps

Contents of the SD card to be used on the Infragram Point and Shoot - an open hardware multispectral camera developed by Public Lab: http://infragram.org
7
star
25

image-sequencer-app

An Image Processing server based on image-sequencer
JavaScript
7
star
26

community-microscope

Community Microscope design files
G-code
6
star
27

leaflet-tile-filter

Multispectral color manipulation and processing (NDVI etc) for Leaflet tile layers with pure JavaScript in Image Sequencer
HTML
6
star
28

mapknitter-exporter

The GDAL/ImageMagick-based exporter system from MapKnitter
Ruby
5
star
29

blurred-location

A JavaScript library to help manage variable location privacy through a "blurred location" model
JavaScript
4
star
30

mapknitter-exporter-sinatra

A minimal Sinatra app to run MapKnitter exports in the cloud
Ruby
3
star
31

plots-leaflet-viewer

A leaflet-based TMS viewer which accepts a TMS URL as a GET parameter. Good for fullscreen map viewing and embedding.
HTML
2
star
32

wherewebreathe

JavaScript
2
star
33

spectralchallenge

a website for Public Lab's Spectral Challenge, at http://spectralchallenge.org
JavaScript
1
star
34

lego-spectrometer

Design files for the Public Lab Lego Spectrometer
1
star
35

thermal-flashlight

Files for the Thermal Flashlight project
C++
1
star
36

multibot

A general-purpose Node.js bot library for writing interactive bot behaviors on various platforms
JavaScript
1
star
37

unearthing-pvd

A platform for historical data-driven analyses of industrial land use, story-mapping, and community organizing. (dataset)
1
star
38

publiclab-kits

Tracker for manufacturing issues for Public Lab kits
1
star
39

spectral-workbench-mobile

PhoneGap-based mobile app version of SpectralWorkbench.org, focus on iOS
JavaScript
1
star
40

SWBSearchModule

The spectral search module for the Spectral WorkBench
Python
1
star
41

leaflet-archive

A Leaflet map that displays geocoded images from Archive.org
JavaScript
1
star