A unidirectional websocket server (and static webserver) to publish messages when someone pushed a hardware buzzer π
This repository contains software to be installed on a Raspberry Pi. Once started it listens on the hardware GPIO pins for signals and publishes them via a websocket server.
The basic idea? Write your frontend and react on buzzer pushes. Start today having fun, and make people happy by providing them an unforgettable time.
For even more context, we recommend reading things with buzzers: building them.
You are missing the context, what this is all about? Have a look at
- (1) things with buzzers: Jeopardy! frontend
- (1) things with buzzers: sports competition frontend
- (3) things with buzzers: hardware
- Features
- Installation
- Usage and configuration
- Test the setup (without buzzer)
- Development
- Contribute
The websocket server is available on the configured HTTP interface + port (default *:8080
) and via the /stream
route: ws://localhost:8080/stream
.
This socket connection is unidirectional. It is a one-way communication. From the Raspberry Pi to the connected frontend/client. Pushing messages back to the Raspberry Pi is not supported (yet).
Have a look at a minimal JavaScript implementation on how to connect to this socket.
The static web server is available on the configured HTTP interface + port (default *:8080
) and via the /static
route: http://localhost:8080/static/*
.
Every file placed in the /static/
folder is available via this server.
A dummy.html file is placed there for testing purposes.
HTTPS is not supported (yet).
The use case of this static webserver:
Write your static frontends (e.g., only with HTML, CSS, and JavaScript), place them in the /static/
folder and have your buzzer-action going!
Sometimes you don't have hardware buzzers available. Either, because you still plan to build them or they are simply at another location and not next to you. But this should not limit us, to build new frontends or experiment with the stack. For this reason and purpose, we have implemented a software buzzer emulation.
Happy emulating!
Telnet
The software buzzer emulation is available on the configured TCP interface + port (default *:8181
) and via TCP clients (e.g., telnet):
$ telnet localhost 8181
Once connected, the server supports the following commands:
Command | Description |
---|---|
/red |
Sends a websocket message "Color: red" / Emulates the red buzzer |
/green |
Sends a websocket message "Color: green" / Emulates the green buzzer |
/blue |
Sends a websocket message "Color: blue" / Emulates the blue buzzer |
/yellow |
Sends a websocket message "Color: yellow" / Emulates the yellow buzzer |
/quit |
Quits the connection |
HTTP
It is also possible to use the emulation via a HTTP request:
curl --header "Content-Type: application/json" --request POST --data '{"color":"red"}' http://localhost:8080/buzz
Available colors:
red
green
blue
yellow
Get the latest release:
Here is the example for macOS / i386:
$ curl -O -J -L https://github.com/andygrunwald/things-with-buzzers-websocket/releases/latest/download/twb-websocket_macOS_i386.tar.gz
$ tar -xvzf twb-websocket_macOS_i386.tar.gz
$ ./twb-websocket -help
Start the binary:
$ ./twb-websocket
2019/10/03 08:33:09 ******************************************
2019/10/03 08:33:09 things with buzzers: websocket
2019/10/03 08:33:09 ******************************************
2019/10/03 08:33:09 Version: v1.0.1-next
2019/10/03 08:33:09 Commit: fdf3574e05a4be75e124ddd09bc03d2c2e45c363
2019/10/03 08:33:09 Date: 2019-10-03T06:33:01Z
2019/10/03 08:33:09 Software buzzer requested
2019/10/03 08:33:09 Starting socket broadcast
2019/10/03 08:33:09 Webserver starting on :8080
2019/10/03 08:33:09 Buzzer emulator: tcp socket starting on :8181
[...]
The help output can be requested with:
$ ./twb-websocket -help
Usage of ./twb-websocket:
-hardware-buzzer
Enforces initialization of hardware buzzer (even on non arm architectures)
-http-listen-addr string
HTTP server listen address (default ":8080")
-tcp-listen-addr string
TCP/Software buzzer server listen address (default ":8181")
-version
Shows the current version
All settings are configurable via commandline flags or environment variables.
Commandline flag | Environment variable | Default value | Description |
---|---|---|---|
-hardware-buzzer |
TWB_HARDWARE_BUZZER |
false |
Enforces initialization of hardware buzzer (even on non arm architectures) |
-http-listen-addr |
TWB_HTTP_LISTEN_ADDR |
:8080 |
HTTP server listen address (default ":8080") |
-tcp-listen-addr |
TWB_TCP_LISTEN_ADDR |
:8181 |
TCP/Software buzzer server listen address (default ":8181") |
The application starts with sane defaults:
- Websocket and Webserver available via port
*:8080
on all interfaces (via HTTP) - Software buzzer emulation enabled and available via port
*:8181
on all interfaces (via TCP/telnet)
PS: Hardware buzzers are not supported on windows.
Start the container:
$ docker run -it -p 8080:8080 -p 8181:8181 -d andygrunwald/twb-websocket
Configure the app via environment variables:
$ docker run -it --env TWB_HTTP_LISTEN_ADDR=":9999" -p 8080:9999 -p 8181:8181 -d andygrunwald/twb-websocket
or via command line arguments:
$ docker run -it -p 8080:9999 -p 8181:8181 -d andygrunwald/twb-websocket -http-listen-addr=":9999"
If you want to mount additional data into the static/
folder, you can mount it to the docker host system:
$ docker run -it -p 8080:8080 -p 8181:8181 -v /Your/Path/To/things-with-buzzers-websocket/static:/go/src/app/static -d andygrunwald/twb-websocket
Let us connect the dots and test the full setup without hardware buzzers and with our software emulation:
- Download the
twb-websocket
binary and start it:./twb-websocket
- Open a browser and go to http://localhost:8080/static/dummy.html
- Open a terminal and connect to the TCP socket:
telnet localhost 8181
- Type
/yellow
into the terminal - You should see a message
{"Color":"yellow"}
in your browser window.
Your test was successful. You are good to go!
$ go build -o twb-websocket
$ GOARM=7 GOARCH=arm GOOS=linux go build -o twb-websocket
$ docker build -t andygrunwald/twb-websocket .
$ go test -v
For our release process, we use goreleaser.com and semantic version:
# Create a new git tag
$ git tag -a v0.1.0 -m "First release"
$ git push origin v0.1.0
# Ship the release
$ goreleaser
This server listens on the following GPIO pins:
GPIO Pin (BCM) | Purpose | GPIO Pin (Physical) |
---|---|---|
21 | Red buzzer | 40 |
20 | Green buzzer | 38 |
16 | Blue buzzer | 36 |
12 | Yellow buzzer | 32 |
The pin-out mapping from the go-rpio documentation is super helpful.
If you want to create and ship awesome things: Go ahead and make this better. Feel free to fork it and play your changes back via a Pull Request.
If you ...
- are unsure
- plan to do a more significant rework
- want to get feedback about the idea before you put the effort in Open an issue and let us talk about your idea.
You have built your own buzzers and did awesome things with it? Write an article in your blog, or tell us the story in an issue or make a Pull Request with a Markdown file. But tell us. Let us know. Inspire us!
We believe that we can do more together. Let's to it together! π