I’m building a tool like Google Analytics for hobbyist makers working on electronics to keep comprehensive descriptions of their projects.
Since I was a teenager I’ve kept up a consistent stream of side projects like multi-touch desks or IoT art installations . If you asked me to repeat any of these projects I would be close to starting over from scratch. I make things as a personal creative pursuit and usually have no need to record what I’m doing. A couple times a year I remember the cool things I did and want to share them. I read through my notebooks, look for hints about how to run the code, and hope there are a couple pictures still on my phone. I rarely have any luck and struggle to get the things working, let alone remember enough to tell others how they could make it too. If you’ve experience this before, this tool is for us.
But it’s not just about having documentation about projects for sharing later. It’s also about having a description of what just happened to think and act on it. Often I’m working and then something unexpected happens. Things suddenly work, things suddenly don’t work, the robot freaks out. I guess what just happened? Often all I have is my mental model of how things should work, the latest source code I’ve uploaded, and maybe some serial logs from the latest test. This isn’t much to go on. If I was doing real engineering, something closer to science, I would want a complete description of what happened. With that I could think through the issue and not blindly guess and check until it works. Guess and check might get results but it won’t teach you what actually happened enough to avoid the same issue in the future.
I was missing a tool that I don’t hear talked about: a tool for seeing. I’ve seen many simple Arduino projects go something like this: Use the Arduino IDE for writing code. If something doesn’t work right, reread the code. Maybe add some serial logs to help debug. Sometimes the text of serial logs isn’t a good representation so we write a custom visualization in Processing. But none of these approaches are both reusable and the visual we wanted. The sweet spot is an extendable library of visualizations on top of a comprehensive store of data. Data should be stored automatically so it can be analyzed, searched, and visualized without planning ahead for it.
Watching a “Desk of Ladyada” video shows how powerful a comprehensive record of the making process is. In the video frame below you see a time synced recording of:
- Code behind the project
- Simple data visualization (bar graph in serial log)
- Closeup video of the project
- Narration by Ladyada
- (During the live stream) A community of people commenting on what was happening
I rarely see so much data synced in such a consumable way. YouTube videos are a nice format for watching but a tool leveraging the same ideas would be interactive.
Bret Victor’s vision of Seeing Spaces crystalized my thoughts in this area.
“I think people need to work in a space that moves them away from the kinds of non-scientific thinking that you do when you can’t see what you’re doing — moves them away from blindly following recipes, from superstitions and rules of thumb — and moves them towards deeply understanding what they’re doing, inventing new things, discovering new things, contributing back to the global pool of human knowledge.”
But a “Seeing Space” was just a vision. I could pursue the idea but I was torn. Was I throwing technology at a problem that could be solved by keeping better documentation? Was I avoiding finishing other projects by starting something new? Was I blaming tools for a lack of persistence?
Whether or not pursuing my own “Seeing Space” was procrastination, it was clear I saw things differently now. In every new project I was frustrated by not being able to see. I started to play with the idea of seeing in my code and electronics. My last two years of repositories on Github shows the progression of my ideas:
- esp8266-ws —Plotting sensor data from a ESP8266 in real time via WebSockets. Seeing real time data from my own project was exciting and something I hadn’t experience before.
- livedata-mqtt — Again plotting live data from an ESP8266 but with the concept of saving separate “tests” of data and a web interface to compare them as small multiples. Small multiples worked well for this sort of data but plotting everything as a line graph was too limiting.
- component-viz — Based on the idea that if you described the display of one data point then you could let the tool connect it to data and make the controls for exploring the data over time. It was a nice abstraction that produced line graphs just as easily as custom visualizations.
- small-multiple-viz — What I thought was going to be the first usable version of my “seeing tool”. It was based on the idea that small multiples are the best way to compare time periods of data. It had a lot going for it: a backend API for saving data over time, a small library of visualizations, and a crude but usable web interface. Good ideas that fell apart when the code got too big to be easily hackable and the interface to manage small multiples got in the way of simply seeing.
- seriallogger2 — I started from scratch and focused on one common use case: writing microcontroller code that outputs serial logs. The tool saves each version of code and the serial log data each version produced. There is a web UI to see the data and keep notes. I tried it out with a couple small projects and although limited, it brought a new level of thoughtfulness and permanence to them. This version had a future.
Where I am now
I am currently using and developing the tool through my hobby electronics projects. I’m focusing on the $19 Wifi-connected Photon microcontroller because of its strong community and web integrations, but any electronics that use code and serial logs would work. A backend API saves data and provides webhooks to get the data. A web UI is used to view and annotate the data.
In this early version the tool has three main views. The first is the command line. The normal commands to upload code to the microcontroller or to show serial log output have been enhanced to send their data to the backend API.
// Display serial logs from the Photon microcontroller and sends
// them to the backend for saving.
particle serial monitor | tee >(python logger.py)
// pfgp“particle flash & git push”
//uploads new code to the Photon microcontroller and sends changes // to the source code to Github for saving.
pfgp PHOTON-IDENTIFIED FIRMWARE-FILE-OR-FOLDER
The second view is the Data Overview. This view shows a timeline of all data sources and a detailed view about the selected time range. Code and serial logs are data sources along with a record of how data was viewed and annotations on any data source. The idea is to store a comprehensive description of how both making and seeing tools were used. For now this description is minimal but you can tell what version of code produced what output. Personally, this is already a big step forward.
The last view is the Notebook. It’s important to go fluidly between exploring data and keeping notes about what is happening. The tool encourages note taking in a format close to how the project could later be shared as a blog post or tutorial. Markdown is used for normal text formatting but with custom components to display the saved data from a particular time period. It’s nice to be writing a plan for a new feature, add a view of the data collected, and then analyze what happened all in the same notebook. Documentation is a lot less work when it is part of the process and not an afterthought.
The ideas I had played with about customizable visualizations, small multiples, live data display, and a more comprehensive description of projects will be brought in with future iterations. The development experience is a little too rough for people to try it out but I’m excited to share updates soon.
If you would like to occasionally hear or discuss my seeing space project, subscribe to me on Medium or reach out to me on Twitter @jhaip.