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.
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.
Also see webjack-firmata, which builds on webjack to provide a browser-based hardware interface for firmata.js.
- If not already done, install the SoftModem Arduino library: https://github.com/arms22/SoftModem
- Choose an example sketch and upload it to your Arduino.
- Now install WebJack with
npm install --save webjack
or
bower install -S webjack
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.
var profile = WebJack.Profiles.SoftModem;
var connection = new WebJack.Connection(profile);
connection.listen(function(data) {
console.log('received: ' + data);
});
connection.send('some data');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.
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.
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.
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:
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.
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
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.
Assuming tape is installed globally:
npm test
Help improve Public Lab software!
- Join the 'plots-dev@googlegroups.com' discussion list to get involved
- Find lots of info on contributing at http://publiclab.org/developers
- Review specific contributor guidelines at http://publiclab.org/contributing-to-public-lab-software