From 741aed961a362d0f27b8df2938ec1605d4af7e80 Mon Sep 17 00:00:00 2001 From: mildmojo Date: Tue, 19 Sep 2017 03:40:12 -0400 Subject: [PATCH] Updates README, adds some config documentation. --- README.md | 35 +++++++++++++++++++++++++---------- config.json.example | 6 ++++++ index.js | 2 +- 3 files changed, 32 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 516c50f..321f0f5 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,9 @@ ## What's this nonsense, then? -This is a Node.js server that exposes the [1000 Buttons Project](http://buttonsare.cool/) -hardware as a web API. Just about every programming environment on the -planet can make web requests. +This is a Node.js server that exposes [@barelyconcealed](https://twitter.com/barelyconcealed)'s +[1000 Button Project](http://buttonsare.cool/) hardware as a web API. Just +about every programming environment on the planet can make web requests. Current code returns each connected serial device's state in a JSON list at `/buttons`. See [JSON Format](#json-format) below. @@ -21,20 +21,25 @@ Made for the [100 Button Jam](https://itch.io/jam/100-button-game-jam). 5. Copy `config.json.example` to `config.json`. 6. Edit `config.json`; enter the names of your serial port(s) that have button controllers attached. -7. Start the server: `node index.js` +7. Start the server: `yarn run server` (or `npm run server`) 8. Visit [http://localhost:3000](http://localhost:3000) to see the debugging page. Verify that it responds (slowly) to button presses on your controller. You're all set! Use any web or HTTP library in any language to connect to [](http://localhost:3000/buttons), then decode the JSON for use in your own software. You can even rip out the contents of `/public` and add your own -web page and javascript there. +web page and javascript there. The server serves any files in `/public`. + +### Configuration + +See [config.json.example](/config.json.example) for details. ## Hardware -This server's designed to talk to a [dirt-simple Arduino sketch](https://itch.io/jam/100-button-game-jam/topic/140791/code-code-for-the-arduino) +This server's designed to talk to a [dirt-simple Arduino sketch](/firmware/100buttons/100buttons.ino) +([original](https://itch.io/jam/100-button-game-jam/topic/140791/code-code-for-the-arduino)) that polls its inputs and assembles multi-byte bitfields representing those -inputs' states. A state packet might look like: +inputs' states. A complete state packet might look like: ``` 02 00 00 00 00 00 00 01 @@ -45,7 +50,7 @@ each byte represent Arduino inputs, with 1 for "button down" and 0 for "button up". A byte with the LSB set is an end-of-message indicator, meaning you can append it to the last 7 bytes you received and start decoding the full bitfield. -## Upsides +## Upsides of a Web API - Every development platform and language has a way of talking to the web, so this opens the 1000 Buttons hardware up to lots of potential users. @@ -54,7 +59,7 @@ append it to the last 7 bytes you received and start decoding the full bitfield. - I got to play with neato Javascript features like async/await, generators, and iterables when I was implementing the server. -## Downsides +## Downsides of a Web API - Untested with the real hardware as of this writing (2017-09-19). - Latency. You can poll pretty fast, but you can't possibly poll the server fast @@ -105,6 +110,7 @@ Likely stuff: responsive with individual button events. - Refactor the serial port code out of `index.js`. It's kinda ugly. - Add a testing mode that sends fake button mashing events. +- Deprecate the XML button mappings in favor of `config.json` settings. Less-likely stuff: @@ -117,7 +123,16 @@ Less-likely stuff: - Add an example Electron desktop app project? - Turn this into an npm package, maybe? I dunno. +## Thanks + +- Thanks to [@barelyconcealed](https://twitter.com/barelyconcealed) for a cool + and ambitious [hardware project](http://buttonsare.cool). So many buttons. +- [Super Soul](http://supersoul.co) for the example [Unity project](https://github.com/supersoulstudio/100ButtonsExample) + I examined for info about decoding the serial protocol + ## LICENSE This code is licensed under the [WTFPL](http://www.wtfpl.net/). See -[LICENSE](/LICENSE) for details. +[LICENSE](/LICENSE) for details, then Do What You Want. + +I like getting credit when you use my stuff, but in this case, you do you. diff --git a/config.json.example b/config.json.example index 7e9828d..5d403b5 100644 --- a/config.json.example +++ b/config.json.example @@ -1,4 +1,7 @@ { + // Set the web server port (you can also use the PORT environment variable) + // port: 3000, + // Adjust the serial port names to match your devices. // E.g. "COM1" (Windows), "/dev/ttyUSB0" (Linux) // "serialPorts": [ @@ -9,6 +12,9 @@ "COM1", "COM2" ], + + // Set XML mappings; the format of these files came from the sample Unity + // project at https://github.com/supersoulstudio/100ButtonsExample "mappingFiles": [ "cal0.xml", "cal1.xml" diff --git a/index.js b/index.js index 5ff7ef9..6fa9a8c 100644 --- a/index.js +++ b/index.js @@ -91,7 +91,7 @@ app.get('/buttons', (_req, res) => { }); -let port = process.env.PORT || 3000; +let port = process.env.PORT || config.port || 3000; console.log(chalk.yellow.bold(`Starting server on port ${port}...`)); console.log(chalk.blue.bold(`Visit http://localhost:${port}/ to see a demo status page.`)); app.listen(port);