Lessons from my first year of live coding on Twitch

I gave streaming a go for the first time last July. Instead of gaming, which the majority of streamers on Twitch do, I wanted to stream the open source work I do in my personal time. I work on NodeJS hardware libraries a fair bit (most of them my own). Given that I was already in a niche on Twitch, why not be in an even smaller niche, like JavaScript powered hardware ;)

Of course I'm not the first to do this. Handmade Hero was one of the first programmers I watched code online, quickly followed by the developers at Vlambeer who developed Nuclear Throne live on Twitch. I was fascinated by Vlambeer especially.

What tipped me over the edge of wishing I could do it to actually doing it is credited to Nolan Lawson, a friend of mine. I watched him streaming his open source work one weekend, and it was awesome. He explained everything he was doing along the way. Everything. Replying to issues on Github, triaging bugs, debugging code in branches, you name it. I found it fascinating, as Nolan maintains open source libraries that get a lot of use and activity. His open source life is very different to mine.

You can even see this comment I left under his video:

youtube comment

I gave it a go myself a week or so later, after setting up my Twitch channel and bumbling my way through using OBS. I believe I worked on Avrgirl-Arduino, which I still frequently work on while streaming. It was a rough first stream. I was very nervous, and I had stayed up late rehearsing everything I was going to do the night before.

The tiny number of viewers I got that Saturday were really encouraging though, so I kept at it. These days I have more than a thousand followers, and a lovely subset of them are regular visitors who I call "the noopkat fam".

We have a lot of fun, and I like to call the live coding parts "massively multiplayer online pair programming". I am truly touched by the kindess and wit of everyone joining me each weekend. One of the funniest moments I have had was when one of the fam pointed out that my Arduino board was not working with my software because the microchip was missing from the board:

I have logged off a stream many a time, only to find in my inbox that someone has sent a pull request for some work that I had mentioned I didn't have the time to start on. I can honestly say that my open source work has been changed for the better, thanks to the generosity and encouragement of my Twitch community.

I have so much more to say about the benefits that streaming on Twitch has brought me, but that's for another blog post probably. Instead, I want to share the lessons I have learned for anyone else who would like to try live coding in this way for themselves. Recently I've been asked by a few developers how they can get started, so I'm publishing the same advice I have given them!

Firstly, I'm linking you to a guide called "Streaming and Finding Success on Twitch" which helped me a lot. It's focused towards Twitch and gaming streams specifically, but there are still relevant sections and great advice in there. I'd recommend reading this first before considering any other details about starting your channel (like equipment or software choices).

My own advice is below, which I have acquired from my own mistakes and the sage wisdom of fellow streamers (you know who you are!).

Software

There's a lot of free streaming software out there to stream with. I use Open Broadcaster Software (OBS). It's available on most platforms. I found it really intuitive to get up and going, but others sometimes take a while to learn how it works. Your milage may vary! Here is a screengrab of what my OBS 'desktop scene' setup looks like as of today (right-click for larger image):

obs screenshot

You essentially switch between 'scenes' while streaming. A scene is a collection of 'sources', layered and composited with each other. A source can be things like a camera, microphone, your desktop, a webpage, live text, images, the list goes on. OBS is very powerful.

This desktop scene above is where I do all of my live coding, and I mostly live here for the duration of the stream. I use iTerm and vim, and also have a browser window handy to switch to in order to look up documentation and triage things on GitHub, etc.

The bottom black rectangle is my webcam, so folks can see me work and have a more personal connection.

I have a handful of 'labels' for my scenes, many of which are to do with the stats and info in the top banner. The banner just adds personality, and is a nice persistent source of info while streaming. It's an image I made in GIMP, and you import it as a source in your scene. Some labels are live stats that pull from text files (such as most recent follower). Another label is a custom one I made which shows the live temperature and humidity of the room I stream from.

I have also 'alerts' set up in my scenes, which show cute banners over the top of my stream whenever someone follows or donates money. I use the web service Stream Labs to do this, importing it as a browser webpage source into the scene. Stream Labs also creates my recent followers live text file to show in my banner.

I also have a standby screen that I use when I'm about to be live:

standby screen

I additionally need a scene for when I'm entering secret tokens or API keys. It shows me on the webcam but hides my desktop with an entertaining webpage, so I can work in privacy:

secret scene

As you can see, I don't take stuff too seriously when streaming, but I like to have a good setup for my viewers to get the most out of my stream.

But now for an actual secret: I use OBS to crop out the bottom and right edges of my screen, while keeping the same video size ratio as what Twitch expects. That leaves me with space to watch my events (follows, etc) on the bottom, and look at and respond to my channel chat box on the right. Twitch allows you to 'pop out' the chatbox in a new window which is really helpful.

This is what my full desktop really looks like:

cropped stream

I started doing this a few months ago and haven't looked back. I'm not even sure my viewers realise this is how my setup works. I think they take for granted that I can see everything, even though I cannot see what is actually being streamed live when I'm busy programming!

You might be wondering why I only use one monitor. It's because two monitors was just too much to manage on top of everything else I was doing while streaming. I figured this out quickly and have stuck with one screen since.

Hardware

I used cheaper stuff to start out, and slowly bought nicer stuff as I realised that streaming was going to be something I stuck with. Use whatever you have when getting started, even if it's your laptop's built in microphone and camera.

Nowadays I use a Logitech Pro C920 webcam, and a Blue Yeti microphone on a microphone arm with a mic shock. Totally worth the money in the end if you have it to spend. It made a difference to the quality of my streams.

I use a large monitor (27"), because as I mentioned earlier using two monitors just didn't work for me. I was missing things in the chat because I was not looking over to the second laptop screen enough, etc etc. Your milage may vary here, but having everything on one screen was key for me to pay attention to everything happening.

That's pretty much it on the hardware side; I don't have a very complicated setup.

If you were interested, my desk looks pretty normal except for the obnoxious looming microphone:

desk photo

Tips

This last section has some general tips I've picked up, that have made my stream better and more enjoyable overall.

Panels

Spend some time on creating great panels. Panels are the little content boxes on the bottom of everyone's channel page. I see them as the new MySpace profile boxes (lol but really). Panel ideas could be things like chat rules, information about when you stream, what computer and equipment you use, your favourite cat breed; anything that creates a personal touch. Look at other channels (especially popular ones) for ideas!

An example of one of my panels:

screenshot of twitch panel example

Chat

Chat is really important. You're going to get the same questions over and over as people join your stream halfway through, so having chat 'macros' can really help. "What are you working on?" is the most common question asked while I'm coding. I have chat shortcut 'commands' for that, which I made with Nightbot. It will put an explanation of something I have entered in ahead of time, by typing a small one word command like !whatamidoing

When folks ask questions or leave nice comments, talk back to them! Say thanks, say their Twitch handle, and they'll really appreciate the attention and acknowledgement. This is SUPER hard to stay on top of when you first start streaming, but multitasking will come easier as you do more. Try to take a few seconds every couple of minutes to look at the chat for new messages.

When programming, explain what you're doing. Talk a lot. Make jokes. Even when I'm stuck, I'll say, "oh, crap, I forget how to use this method lemme Google it hahaha" and folks are always nice and sometimes they'll even read along with you and help you out. It's fun and engaging, and keeps folks watching.

I lose interest quickly when I'm watching programming streams where the streamer is sitting in silence typing code, ignoring the chat and their new follower alerts.

It's highly likely that 99% of folks who find their way to your channel will be friendly and curious. I get the occasional troll, but the moderation tools offered by Twitch and Nightbot really help to discourage this.

Prep time

Automate your setup as much as possible. My terminal is iTerm, and it lets you save window arrangements and font sizes so you can restore back to them later. I have one window arrangement for streaming and one for non streaming. It's a massive time saver. I hit one command and everything is the perfect size and in the right position, ready to go.

There are other apps out there that automate all of your app window placements, have a look to see if any of them would also help.

Make your font size really large in your terminal and code editor so everyone can see.

Regularity

Be regular with your schedule. I only stream once a week, but always at the same time. Let folks know if you're not able to stream during an expected time you normally do. This has netted me a regular audience. Some folks love routine and it's exactly like catching up with a friend. You're in a social circle with your community, so treat it that way. I want to stream more often, but I know I can't commit to more than once a week because of travel. I am trying to come up with a way to stream in high quality when on the road, or perhaps just have casual chats and save programming for my regular Sunday stream. I'm still trying to figure this out!

Awkwardness

It's going to feel weird when you get started. You're going to feel nervous about folks watching you code. That's normal! I felt that really strongly at the beginning, even though I have public speaking experience. I felt like there was nowhere for me to hide, and it scared me. I thought, "everyone is going to think my code is bad, and that I'm a bad developer". This is a thought pattern that has plagued me my entire career though, it's nothing new. I knew that with this, I couldn't quietly refactor code before pushing to GitHub, which is generally much safer for my reputation as a developer.

I learned a lot about my programming style by live coding on Twitch. I learned that I'm definitely the "make it work, then make it readable, then make it fast" type. I don't rehearse the night before anymore (I gave that up after 3 or 4 streams right at the beginning), so I write pretty rough code on Twitch and have to be okay with that. I write my best code when alone with my thoughts and not watching a chat box + talking aloud, and that's okay. I forget method signatures that I've used a thousand times, and make 'silly' mistakes in almost every single stream. For most, it's not a productive environment for being at your best.

My Twitch community never judges me for this, and they help me out a lot. They understand I'm multitasking, and are really great about pragmatic advice and suggestions. Sometimes they bail me out, and other times I have to explain to them why their suggestion won't work. It's really just like regular pair programming!

I think the 'warts and all' approach to this medium is a strength, not a weakness. It makes you more relatable, and it's important to show that there's no such thing as the perfect programmer, or the perfect code. It's probably quite refreshing for new coders to see, and humbling for myself as a more experienced coder.

Conclusion

If you've been wanting to get into live coding on Twitch, I encourage you to give it a try! I hope this post helped you if you have been wondering where to start.

If you'd like to join me on Sundays, you can follow my channel on Twitch :)

On my last note, I'd like to personally thank Mattias Johansson for his wisdom and encouragement early on in my streaming journey. He was incredibly generous, and his FunFunFunction YouTube channel is a continuous source of inspiration.

Prettify your Windows terminal

I do my personal coding on a Macbook Pro running macOS. My favourite terminal application is iTerm2, and I use it daily when working on open source software. You can tweak the appearance and behaviour of iTerm2's console really easily and in a granular fashion.

I also own a Windows desktop machine, which I have around to test my own software on. It took me a while to get a pretty and cohesive experience set up for an enjoyable experience on Windows, so I am sharing my setup with you in case you would also like a similar aesthetic.

First things first - there is a rad NodeJS terminal app written in Electron called hyper that you can install and will require less tweaking than my setup. I chose not to run hyper because my machine does not have super impressive hardware specs. The machine runs too slowly to support an Electron app in addition to my web browser and code editor, because Electron apps are a Chrome browser and NodeJS process in one running package. Running a native terminal application makes a bit more sense for my use case.

Here is what the final result looks like:

The whole desktop (view image in a new tab to zoom):

pic of the screenshot of consolez

If you'd like a similar look, here are the steps involved:

1. Install Github Desktop

The most efficient way to get a 'unix-like' experience on Windows is to install git bash via Github Desktop. Using git bash is a big win for unix-like shell command consistency, and you'll have git automatically installed and working out of the box for you.

Download Github Desktop for Windows and install it. When you run it for the first time, it'll prompt you to log in with your Github account. Once you're all logged in, leave Github Desktop open for later.

2. Configure your prompt

You can now run the Shell program included with Github Desktop by finding it in your Start menu under the Github directory. The terminal that opens is running git-bash, and you should find git working out of the box, as well as the typical unix commands such as ls, cat etc.

if you'd like to tweak your shell prompt, you should be able to find it by looking in your user directory's AppData/Local files. The full path will probably look something like this:

C:\Users\<your username>\AppData\Local\GitHub\PortableGit_1234…\etc\profile.d\git-prompt.sh

You can reference / use my shell prompt to get started, if you like! It is below.

But the terminal still doesn't look super pretty yet, huh? Not to worry! Let's use consoleZ to tweak the appearance a little further!

3. Install and configure consoleZ

consoleZ is a wrapper application for your terminal of choice. It unlocks some cool appearance configurations that you won't get by running git-bash or Powershell alone. It's the best one I've found to have control over fonts, colours, background transparency, etc.

Install consoleZ by following the instructions in the consoleZ repo's README.

Once you boot it up, open the settings by hitting Ctrl + S, and you'll see lots of settings you can tweak to your heart's content. Before you do that though, we need to tell consoleZ to run our git-bash shell that Github Desktop installed for us. Under the 'Console' pane of the settings, in the 'Shell' input field, type bash.exe —login -i.

Once you save your settings, you might notice that consoleZ pops up an error and doesn't work anymore! Not to worry, we're going to fix that in the next step!

4. Point Github Shell at consoleZ

Switch back to Github Desktop. Open up the settings pane by clicking the little gear on the top right of the Github Desktop GUI. Within the 'Default shell' section, choose 'Custom' and fill in the input underneath with the path to where you installed consoleZ (it might be different to my example below):

pic of github desktop settings

5. Start up Github Shell

In order to start up your terminal from now on, you'll need to run Github Shell. You have a couple of options to do this. You'll find it in your Start menu under Github, you can pin it to your tiles in your Start menu as a shortcut, or you can launch Github Shell from the Github Desktop application.

If all has been set up correctly, you should see consoleZ start up, with git-bash running inside! Yay! From here, you can access the settings and tweak the appearance and other properties to your heart's content.

I am using a colour theme called 'space gray'. If you'd like to reference or start with my configuration file instead of manually doing it in the settings, go for it! You should be able to find your consoleZ settings by looking for a console.xml file in your user's AppData/Roaming directory. My path looks like this:

C:\Users\<your username>\AppData\Roaming\Console\console.xml

Enjoy your pretty terminal! If you follow these steps and they work out for you, I'd love to see you share a screenshot in the comments!

Wireless 3D printing station

pic of raspi and octoprint

When I first got into 3D printing, I'd been outsourcing all of my printing needs to Shapeways. I was working on a brand new jewellery range at the time, and was prototyping different forms. I wouldn't call that rapid prototyping though, given the wait on even plastics used to be two weeks at the time. They turn things around a lot faster these days, though!

A year or two later I moved to a city which was about to open a hackerspace in the downtown area. Once it opened, three 3D printers were available to use, which stepped up my access to printing things that I needed. This was a pretty big deal, because I got to learn how to use the machines. The process was no longer abstracted away. I could turn around things much faster as well if I needed to.

I remember when I then bought my first 3D printer kit for my home. It was deliriously exciting to think that I could print any time I wanted, and tweak a myriad of settings to perfect the output without annoying others.

The 3D printing workstation came about in two stages: convenience first, and then later, space.

I lived by myself in a rather generously sized, stupidly affordable two bedroom condo at the time. The printer took pride of place in my rather large study. This study easily held two work tables and a rather bulky writing desk. I had a sewing station, a computer station for my coding needs, and a dedicated place for my new 3D printer as well.

It became apparent rather quickly though, that I was constantly tethered to the printer in some way. I started by printing via a USB connection to my computer. This was a rather terrifying endeavour. One tiny interruption would be catastrophic for your currently running print job. Say, you're four hours into a five hour print, going strong. You forget you're tethered and click 'yes' to a software update, which you didn't notice would require a restart of your computer. Welp, you just halted the print, and in most cases this is not recoverable. Perhaps your friend would like to Skype with you, and you have to turn her down because you're stuck next to a bunch of noisy stepper motors on a vibrating printer for the next two hours. You get my drift!

I also tried printing from an SD card, however I found that I was continually running back and forth between the computer and the printer, reloading and starting up a gcode file that had been tweaked in some minute way for better settings. It was better, but not optimal.

I started looking into other options online, and stumbled upon Octoprint. It was written by Gina Häußge, and BQ recently sponsored work and maintenance on it going forward. Octoprint is a wonderful python based service that can run on any computer attached to a 3D printer. It serves up a web app, meaning you can access this web app simple by visiting the IP address of the computer you have it running on. You can upload gcode files, run gcode commands on the printer, and start print jobs all from the web interface.

I took the path that most have, and decided to run Octoprint from a Raspberry Pi. The Raspberry Pi is ideal, because it's a very small computer capable of running Octoprint just fine (in fact I'm still using my old Pi model B!). It doesn't take up to much desk space either which is really nice. Having a little machine dedicated to running the 3D printer has really made things so much more convenient.

Getting up and running on Octoprint is pretty straightforward. You can install it yourself on a Raspberry Pi, or you can download a pre-made Raspian image with Octoprint ready to go made by Guy Sheffer called OctoPi, which is even easier.

Here is a screencast I recorded of my old printer running on Octoprint. Octoprint supports webcam streaming and timelapse recording which is an awesome feature you'll notice in the video below:

And an example of a timelapse from Octoprint, also on my old printer:

Pretty neat, huh!

Fast forward to last year. New year, new printer (!!), new city, and new apartment! The new city/apartment caused a fresh problem. This was New York City. I am sharing a rather tiny two bedroom apartment with my partner. I downsized a LOT to make this happen. I got rid of my old writing desk, and my partner uses one of the work tables as the desk he works from every day (he works from home).

When we bought a new, larger printer, we had to place it straddling our two small work tables. This ate into our desktop space, was really noisy, and it shook the two tables as it printed. Not ideal!

Given the limited space we have in the study (second bedroom), I window shopped online until I found the Stuva Storage Combination from Ikea.

pic of stuva from ikea website

I picked it up for $135 plus additional for delivery (NYC = I got rid of my car). What sold the Stuva for me was how narrow it is (we had managed to create only a tiny space for the new printer location), and how much storage it had. Finally, we'd be able to unpack the rolls of filament from the cardboard boxes in the closet!

What we really wanted was for the printer to sit on top of the workstation and nothing else. The Raspberry Pi, the wifi extender, and the power supply should be hidden away. We installed the shelf inside the Stuva in a high position (after measuring the height of the power supply) in order to achieve this.

This is the final result, squished into our study right next to the entrance:

pic of the station1

When we're worried about draughts (rarely, because we mostly print in PLA) we just close the door, and open the window on the other side of the room to prevent overheating / provide ventilation.

The wireless setup inside:

pic of the station2

Bottom drawer, full of filament:

pic of the station3

It looks beautiful, frees up desk space, and allows storage of filament, kapton tape, tools, etc right with the printer. Win win!

I'd love to see other printer setups, feel free to comment with photos below!

Using Johnny-Five within an Electron app

Johnny-Five is a pretty fabulous NodeJS based robotics library. You can use it to create all sorts of things!

Running your Johnny-Five application within Electron is a great way to add a user interface to your robotics. It does require a couple of additional steps to get it up and running correctly, however, so I have outlined them below.

  1. Serialport will probably fail to be found by Electron's Node process. We can fix it! Follow the steps in a previous post of mine to get this going, making sure the rebuild and rename steps are performed on the serialport directory within ./node_modules/johnny-five/node_modules/ instead of a fresh serialport install.

  2. Johnny-Five uses process.stdin, which is not available for Electron's use. This causes Electron's render process to crash! We can reroute process.stdin to a compatible replacement stream though, to get around this. Before you do any of your regular Johnny-Five code, paste the following into your JavaScript file you're using within Electron:

var Readable = require("stream").Readable;  
var util = require("util");  
util.inherits(MyStream, Readable);  
function MyStream(opt) {  
  Readable.call(this, opt);
}
MyStream.prototype._read = function() {};  
// hook in our stream
process.__defineGetter__("stdin", function() {  
  if (process.__stdin) return process.__stdin;
  process.__stdin = new MyStream();
  return process.__stdin;
});

// then Johnny-Five code goes below here!

Thanks to Rick Waldron for this last step, which he wrote up for a different use case (NW.js) but it works great for Electron too. I just copied the code straight from the before mentioned link.

Let there be light! You should now be able to run your Electron app as normal and blink that LED!

yellow johnny-five logo

The avrgirl project: manual testing

green baseball cap with the letters 'AVR' written on it

Publishing your code for others to use is a scary, but often rewarding accomplishment. It can be really exciting to witness peers and strangers incorporating a library of yours into their own projects.

Being an open source maintainer brings a lot of responsibilities to the table. Managing issues, pull requests, and emergency bug fixes can be a lot for one person to deal with. If your project cannot rely solely on automated testing, this can be a real burden. This is particularly true in the hardware library scene. I have experienced all sorts of weird bugs pop up when the same code worked the day before. Things like operating system changes and runtime upgrades can expose the fragility of how some hardware libraries work, more readily then something, say, a web based library.

I have run into this recently when publishing and maintaining libraries falling under the AVRGirl project, which I started working on in early June last year. While I have learned a lot during the process, there is still a lot more for me to know. These gaps in knowledge often manifest into slightly different experiences across users' operating systems and versions of NodeJS, which is what all AVRGirl packages are written in. When I say 'experiences', what I really mean is bugs, of course ;)

When I write unit tests for AVRGirl, the most notorious parts of working with hardware get stubbed out. This is stuff like serial interfaces, and responses from hardware are faked. This tends to be where a lot of things go wrong, and where compatibility issues rear their ugly head. In other words, my code needs to know about all of the edge cases and fragilities, and provide for them. Simulating this kind of stuff in unit tests is not at all practical and introduces some tech debt and readability issues for potential contributors. It also doesn't help me stay on top of OS and NodeJS version changes, and their effect on my libraries/code.

The problem

So let's break down exactly what all this means. We'll focus on one library in particular, which is AVRGirl Arduino. AVRGirl Arduino flashes precompiled code to a myriad of supported Arduino boards. What does this look like, in testing terms?

  1. 16 supported boards
  2. OSX, Windows, Linux (and all modern releases/versions within)
  3. NodeJS versions 0.10, 0.12, 4.x, and 5.x (currently alpha testing 5.x so we won't count it)

This works out to be approximately 144 integration test cases, if we're just counting operating systems as giant buckets, and not splitting them out to things like OSX Yosemite, El Capitan etc etc.

What I'm getting at here, is that I cannot sit down and manually test everything alone for both releases and environment changes/additions. Well, that and hold down a full time job and occasionally not code from time to time :P We all need time away.

AVRGirl Arduino was picking up a bit of interest a couple of months after releasing the first version, so I decided to reach out to potential testers by opening the following issue.

screencap of issue #4 under avrgirl-arduino github repository

It was a quick explanation of what I wanted and why. I added the 'help wanted' label and thought that would be it. After mostly radio silence, I started thinking long and hard about why I've had no shortage of developers opening pull requests with new features and bug fixes, but not a lot of feedback around if the library actually works as expected in these 144 different combinations. No one was chomping at the bit to sit down and plug in a bunch of boards and run some quick set up code.

Wait, but that was just it! I had not provided an easy way to manually test AVRGirl Arduino. Sure, I'd written some vague instructions in a Github issue, but that's not a very good experience for people wanting to help. I identified a few things that would need to be better if I was going to ask others to manually test for me:

  1. Manual testing is boring for most people
  2. You don't get a 'little green square' contribution reward for manually testing
  3. People who are new to hardware probably had no idea where to start even if they wanted to help. My issue made a lot of assumptions about others' knowledge, which is not inclusive.
  4. There were too many steps involved and too many bridges to cross in order for someone to invest in helping. People's time is valuable and I was not respecting that.

A proposed solution

I decided to write a small app to run within AVRGirl Arduino, its only job being to allow an easy way to manually test AVRGirl Arduino. Embedding it within the library itself allows for great portability, and no additional installation of anything else needed should someone like to help test. The downside is that it introduces more dependencies to AVRGirl, which carries more risk for issues. I tried to keep it relatively lightweight to mitigate this.

I called it AVRGirl Test Pilot, and connected it to the CLI tool within AVRGirl Arduino. The 2 steps required to start testing are:

  1. With NodeJS installed, run npm install -g avrgirl-arduino
  2. Run avrgirl-arduino test-pilot

That's it! A local server will spin up and a browser window will open with a prompt to log in via their Github account:

screenshot of login screen

Once logged in, the user will see the following steps to follow:

screenshot of 3 steps

The test process simply uploads some code to their Arduino and verifies it worked. The resulting report is automatically generated for them to submit:

screenshot of report screen

Submitting that form will send the report details to a remote database that I host. The screenshot above shows what details I'm after when the test is complete:

  1. The Arduino board they were testing with
  2. NodeJS version they're using
  3. Operating system and version
  4. Version of AVRGirl Arduino
  5. Version of Test Pilot
  6. Who the tester is (optional)
  7. Additional notes (optional)
  8. Any errors that might have been returned

This info is enormously useful for me. It gives me a place to start, and doesn't require the tester to go in and open an issue on the Github repository (where I would then begin to ask them a million questions about what software and hardware they were using etc).

In time when I finish setting up the Github organisation for AVRGirl, if the testers opted in, they'll be invited to be part of the awesome testers team within the organisation. This gives them a little 'badge' for their Github profile, which I hope will be seen as a nice little gesture to say 'thank you'.

So far, I've had two bugs come in from submitted reports, which had already made the efforts behind Test Pilot worth it. I'm especially curious to see if Test Pilot will help hardware beginners to feel less intimidated helping out with a project such as AVRGirl.

If you'd like to be a test pilot for AVRGirl Arduino, check out the 2 steps mentioned earlier in this blog post, or find help in the README of the AVRGirl Arduino repository on Github. And thank you so much in advance! <3

Using node-serialport in an electron app

So you want to create some serialport magic within an electron app? Right on, that sounds like you're creating something pretty amazing for the desktop!

In the past this scenario has been a pretty tough feat to achieve, however with the convergence of NodeJS and iojs into NodeJS 4.x, the road to serialport fun for desktop apps is a much shorter and more enjoyable one.

The following instructions are designed with Linux and OSX operating systems in mind.

Important note: if you have installed NodeJS version 4.x or greater, and are using at least electron-prebuilt version 34.0.1, you may not need all of the steps below anymore. In a lot of cases, simply running npm install serialport within your electron application directory, and requiring/using serialport as you usually do should work just fine!

Let's do this.

Steps for success

Make sure you're on NodeJS version 4.0 or higher.

I'm going to assume you have already installed electron-prebuilt for your machine. If not, run:

npm install -g electron-prebuilt  

Next, set up your electron app boilerplate if you haven't already. This is essentially creating the following files in an empty directory:

  • package.json
  • main.js
  • index.html

See the electron quick start docs for how to set these files up.

Ok! Now let's install serialport. Run this from the root directory of your app:

npm install --save serialport  

You'll notice that a node_modules dir will appear, with serialport within. So far so good. At this point, you could try requiring serialport within your electron's index.html file and see if it works as expected. If it doesn't, never fear, let's try the additional steps below!

We gotta rebuild serialport to work with electron. To do this, we need to install electron-rebuild:

npm install --save-dev electron-rebuild  

The last step is to run electron-rebuild, once again, just in the root directory of the app:

./node_modules/.bin/electron-rebuild -$(electron -v)

A quick test dropped into index.html would look like this:

<script>  
  var sp = require('serialport');

  sp.list(function(err, ports) {
    console.log(ports);
  });
</script>  

Woo! We can now run electron and start up our app:

electron .  

Uh oh! Do you see the following error in your electron app's console?

Uncaught Error: Cannot find module '~/my-electron-app/node_modules/serialport/build/serialport/v2.0.2/Release/node-v46-darwin-x64/serialport.node'

This be an unfortunate issue. But this is pretty easy to fix for now :)

If you rename the directory within Release to what the console output is expecting, you're right as rain and it'll find the serialport.node file correctly. Have a look in the Release directory to see what the child directory was named instead, and rename it.

Example:

mv ~/my-electron-app/node_modules/serialport/build/serialport/v2.0.2/Release/electron-v34.0.1-darwin-x64 ~/my-electron-app/node_modules/serialport/build/serialport/v2.0.2/Release/node-v46-darwin-x64  

Try running your electron app again, or refresh it with Cmd/Ctrl + R. You should see a bunch of ports listed within an array in your console this time! Sweeeeeet.

Looks like @stevekinney and I are no longer NodeJS desktop app frenemies.

Have fun!