Beyond the Grid: Interactive Installations with Wacky Topologies
Drawings and diagrams may be found here
-
Make sure you have downloaded and installed the required software:
- Visual Studio Code from https://code.visualstudio.com/
- We'll use this to write code and to run our creative coding environment for developing animations for installations
- NodeJS (includes
npm
, the node package manager) (you can get it from https://nodejs.org/en/download/)- If prompted, make sure to add
npm
to your path - We need this in order to run Javascript code that talks to a microcontroller
- If prompted, make sure to add
- Rhino (includes Grasshopper) from https://www.rhino3d.com/download/
- We'll use this to create mappings we can use in creative coding
- The Arduino IDE from https://www.arduino.cc/en/software
- We'll use this to upload code to the microcontroller
- Any modern web browser. The latest versions of Google Chrome, Microsoft Edge, Firefox, and Safari should all work.
- We'll use this to visualize, tweak, and debug our animations
- Visual Studio Code from https://code.visualstudio.com/
-
Download the repository from https://github.com/Julian-Behnaz/DigitalFutures2021/
-
Open the
workspace.code-workspace
file in Visual Studio Code- The first time you do this, VSCode will prompt you whether you trust the workspace. We recommend you click yes, but everything we'll be doing will work even if you "browse folder in restricted mode". This is a new VSCode security feature you can learn about here: https://code.visualstudio.com/docs/editor/workspace-trust
-
Open a new terminal in Visual Studio Code
-
See https://code.visualstudio.com/docs/editor/integrated-terminal for instructions
-
Select the
server
directory as the working directory for the terminal
-
-
Install the NodeJS dependencies we'll use to talk to the microcontroller by typing this command in the terminal and pressing the "enter" or "return" key:
npm install
-
Run the creative coding environment server from the terminal by typing this command and pressing the "enter" or "return" key:
npm run start
This will start a program that acts as a web server and as a conduit to send animations from your computer to your microcontroller.
-
Open the url indicated in the terminal (you might have to scroll up to see it). You can also copy from here:
http://localhost:8080
This will open our custom installation visualization environment:
The code we provide comes with several different folders. Here's an overview of the ones you might need to care about:
server
front
mappings
- a folder containing.json
files with different LED position mappings. You'll export files into this folder from Grasshopper and load them inmain.js
.index.html
- the HTML file that importsmain.js
. You probably won't want to change it. It provides automatic error detection/recovery and reloads the browser when the server tells it that files have changed.main.js
- the main javascript file that runs in the browser. You'll spend most of your time here, writing animations. Note that the file is very long, but don't worry; you don't need to understand it all. There's a playground section at the bottom where you'll write your code. The rest of it provides a creative coding environment and defines functions you can use.
index.js
- the server code that talks to the web browser and microcontroller. You'll only need to change this if it can't find your microcontroller see here or if you need to tweak something like the microcontroller baud rate.
microcontroller
src
src.ino
- The microcontroller code you need to tweak and upload to your Arduino.
platformio.ini
- You can upload code to an Arduino directly from within Visual Studio Code using the PlatformIO extension instead of the Ardiono IDE. It's fantastic when it works but can be a bit tricky to set up, so we won't cover it during the workshop. If you have a working PlatformIO installation and want to use it, modify this file to choose to which microcontroller you want to upload your code.
You can run the installation visualizer without connecting a microcontroller, but at some point you'll actually want to try out your animations on real hardware. Every setup is slightly different, so you'll need to tweak a few things.
-
In the Arduino IDE, install the FastLED library:
-
Configure the Arduino IDE to use an external editor so that Visual Studio Code and the Arduino app don't fight over which one is allowed to edit files:
-
Open
microcontroller/src/src.ino
in Visual Studio Code -
Modify
NUM_LEDS
to match the total number of individual LEDs you will be controlling in total. If you have multiple LED strips, add up the number in every strip. -
Modify the
setup
function to have the correct- number of LED strips you have
- type of LED strips
- color ordering of each LED strip
- number of LEDs in each strip
-
Upload the code to your Arduino.
- IMPORTANT: make sure your server isn't running in any terminal — it will try to communicate with your microcontroller, and you can't upload code to it while something else is trying to communicate with it.
- To do this, hit the Control+c keys in the terminal where you ran
npm run start
to stop it (yes, it's the actualcontrol
key, even on a Mac. Don't use Command+c; it won't work)
- To do this, hit the Control+c keys in the terminal where you ran
- Open
microcontroller/src/src.ino
in the Arduino IDE - Make sure your microcontroller is connected to your computer
- Select your port and board
- Compile and upload your code to the microcontroller
- IMPORTANT: make sure your server isn't running in any terminal — it will try to communicate with your microcontroller, and you can't upload code to it while something else is trying to communicate with it.
We've tested the server on Windows and MacOS and it should be able to find official Arduino Uno boards and Teensy 3.1, 3.2, 3.5 boards. When you have the server running with npm run start
and connect one of these microcontrollers, you should see a message that says status: 'Connected'
in the terminal. If this doesn't happen, you might have a microcontroller with a vendor id we didn't account for. Here's how to fix that problem:
-
Open
server/index.js
in Visual Studio Code. -
Modify the function
isDesiredPortInfo
to return true ifportInfo
matches the board you want to detect. You can look at the terminal output when the server is running to find the properties of your specific connected devices so that you can use one or more of those values in theisDesiredPortInfo
function.
Sometimes things go wrong. Check these things:
- Have you configured and uploaded the microcontroller code (while the server wasn't running)?
- Is the server running? (
npm run start
in theserver
directory) - Is the microcontroller physically connected to the computer?
- Has the server found and connected to the microcontroller? (see this if it hasn't)
- Is the browser window open to the correct URL? (note that you have to refresh the browser window if you stop the server and restart it, and only one browser window can talk to the server at a time to avoid conflicts between messages intended for the microcontroller)
- Does the number of bytes sent from the server match the number of bytes the microcontroller is expecting? (if not, check to make sure that the browser is sending the server 3x the number of bytes as you have LEDs and that the microcontroller code is configured for the correct number of LEDs)
- (If animations are showing up on the strip(s) but the colors are wrong) Does the channel ordering specified in the microcontroller code match the requirements of your LED strip(s)? See if
RGB
,RBG
,GRB
,GBR
,BRG
, orBGR
would be the correct ordering. Also check if you've specified the correct chipset for your LED strip. Consider running a FastLED example program.