From 6ed59dfff21002b39ad5221d650f69d3aa0c1092 Mon Sep 17 00:00:00 2001 From: Katz Date: Tue, 23 Jun 2020 22:55:00 -0700 Subject: [PATCH 1/3] Add PiControl documentation --- docs/picontrol.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 78 insertions(+) create mode 100644 docs/picontrol.md diff --git a/docs/picontrol.md b/docs/picontrol.md new file mode 100644 index 0000000..62f667e --- /dev/null +++ b/docs/picontrol.md @@ -0,0 +1,77 @@ +PiControl is TreeHacks' NFC check-in and attendee tracking system, used at TreeHacks 2020. With PiControl, hackers badge into various events by tapping their id cards onto "cubes" equipped with NFC readers. + +## ID badges + +At TreeHacks 2020, we printed a custom badge for every hacker. We used [these pvc id cards](https://store.gototags.com/nfc-pvc-badge-vertical) and an ID card printer (TODO: which one? although any should work). + +The process we eventually used relied on the hardware IDs for each card being unique. This means that NTAG210-215 and MIFARE cards should work, but to be safe you should check the specification for the protocol you're planning on using to make sure that there won't be any ID collisions. From our research, it seems that most manufacturers like to assign IDs in sequence, but that's obviously not guaranteed. + +## Hardware + +Our hardware "cube" were assembled from the following: + +- A plastic cube case. These were surprisingly hard to find, so we bought [these](https://www.amazon.com/Mr-Go-Rechargeable-Soothing-Decorative-Nightstand/dp/B01E7685IG/ref=sr_1_2?dchild=1&keywords=Mr.%2BGO%2Blight%2Bcube&qid=1592967810&sr=8-2&th=1) and replaced their internals with our hardware. + +- Raspberry Pi Model 3b+ (but any Raspberry Pi with Wifi capability should work) + +- [USB NFC readers](https://www.amazon.com/gp/product/B07Q5KXM6J/ref=ppx_yo_dt_b_asin_title_o06_s00?ie=UTF8&psc=1). These emulate a keyboard -- when an NFC badge is scanned onto them, they 'type' its ID into whatever they're connected to. + - **PLEASE** make note of the model: if that link isn't dead, you'll see it links to a '14H' reader. '14H' (or '14D') is required to get the specificity necessary to distinguish between the NFC badge IDs: these readers read the most significant bit first, and since the card IDs are assigned sequentially this means that most of them have the same first 8-10 hex digits. You are in for much pain if you do not purchase the correct readers. +- Microusb battery pack. Best to get flat ones. +- *Optionally*: LEDs + +### Hardware: Future Considerations + +- Raspberry Pi's are certainly overkill for this application. Since the boxes only need to make a single web request, a simpler IoT board (eg. ESP8266 or ESP32) would work just as well, consume far less power, and cost an order of magnitude less. + - As a corollary, "PiControl" is probably a bad name for this system as pretty much all of the logic is hardware-agnostic. Even the small Python script run on the Pi could probably run on a much simpler microcontroller (with a couple modifications) through Micropython. +- The keyboard emulation NFC readers were used because Katz (the author of this doc) had never touched hardware in his life and thus couldn't figure out how to use the [an actual breakout board](https://www.adafruit.com/product/364). In the first week of CS107e, he realized that he was connecting the board's TX and RX pins to the Pi's TX and RX pins (respectively). He has now learned that TX == "transmit" and RX == "receive" and thus TX on one board should be connected to RX on the other and vice versa. If you ever see Katz, feel free to chastise him for his foolishness. + +## Software + +### On the Pi + +The script run on the Pi can be found at https://github.com/MYKatz/PiControl. If you're using the aforementioned USB NFC readers, you should be running 'read_keyboard.py'. + +The script is very simple: upon receiving input from the NFC reader (a card's ID), it sends that to a specified API endpoint. + +#### OS and dependencies + +We used a standard install of Raspbian. You will need to configure the Pi to connect to Wifi -- there are many guides online to do this, such as [this one](https://raspberrypihq.com/how-to-connect-your-raspberry-pi-to-wifi/). + +An installation of Python 3.7 should include all of the necessary dependencies except for [Requests](https://requests.readthedocs.io/en/master/). A 'pip3 install requests' should work, provided you're connected to the internet. + +### Web App + +The PiControl web app comprises the vast majority of the logic. You can find it [here](https://github.com/treehacks/picontrol). + +PiControl is developed on Postgres, Go (w/ Gin), and React. You can call this the PGRG stack if you hate pronounceable acronyms. + +When the script on a Pi is ran for the first time, the Pi is registered with Picontrol and will show up on the 'Pis' page. You can then name the Pi and associate it with an event. When badges are scanned onto the Pi, they'll appear in the logs. + +#### Eventive Integration + +PiControl works by scanning NFC IDs into events on Eventive, which does the heavy lifting matching these IDs to hackers. If you're going to use Eventive (and you probably should, it's great!) then remember to update the EVENTIVE_API_KEY environment variable and change the eventive API link in the code (which is currently hard-coded.. oops!) + +#### Environment Variables + +``` +DATABASE_URL= /* postgresql uri string */ +EVENTIVE_API_KEY= +GIN_MODE=release /* either 'debug' or 'release' */ +PASSWORD= + +``` + +#### Development Set-up + +- Set "homepage" in package.json to the url you want. +- Run `go get -u github.com/gin-gonic/gin github.com/joho/godotenv github.com/lib/pq` +- Run `npm run dev-start` + +Pushing and pulling to docker: https://ropenscilabs.github.io/r-docker-tutorial/04-Dockerhub.html + +#### Installation + +- Build using the dockerfile +- Get the build onto your server +- create .env file +- $ sudo docker run -d -t --env-file=".env" -p 80:80 [container id] \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 7ae5c21..71ba1e1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -36,6 +36,7 @@ nav: - Cog: cog.md - Gavel: gavel.md - Submit: submit.md + - PiControl: picontrol.md - DevOps: DNS: devops/dns.md AWS Inventory: devops/aws-inventory.md From 2896f8d1a50e9e154dc061c16d706ce0e6573b4e Mon Sep 17 00:00:00 2001 From: Matt Katz Date: Wed, 24 Jun 2020 20:29:29 -0700 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Ashwin Ramaswami --- docs/picontrol.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/picontrol.md b/docs/picontrol.md index 62f667e..7074cb3 100644 --- a/docs/picontrol.md +++ b/docs/picontrol.md @@ -1,8 +1,8 @@ -PiControl is TreeHacks' NFC check-in and attendee tracking system, used at TreeHacks 2020. With PiControl, hackers badge into various events by tapping their id cards onto "cubes" equipped with NFC readers. +PiControl is TreeHacks' NFC check-in and attendee tracking system, used at TreeHacks 2020. With PiControl, hackers badge into various events by tapping their ID cards onto "cubes" equipped with NFC readers. ## ID badges -At TreeHacks 2020, we printed a custom badge for every hacker. We used [these pvc id cards](https://store.gototags.com/nfc-pvc-badge-vertical) and an ID card printer (TODO: which one? although any should work). +At TreeHacks 2020, we printed a custom badge for every hacker. We used [these PVC ID cards](https://store.gototags.com/nfc-pvc-badge-vertical) and an ID card printer (TODO: which one? although any should work). The process we eventually used relied on the hardware IDs for each card being unique. This means that NTAG210-215 and MIFARE cards should work, but to be safe you should check the specification for the protocol you're planning on using to make sure that there won't be any ID collisions. From our research, it seems that most manufacturers like to assign IDs in sequence, but that's obviously not guaranteed. @@ -12,32 +12,32 @@ Our hardware "cube" were assembled from the following: - A plastic cube case. These were surprisingly hard to find, so we bought [these](https://www.amazon.com/Mr-Go-Rechargeable-Soothing-Decorative-Nightstand/dp/B01E7685IG/ref=sr_1_2?dchild=1&keywords=Mr.%2BGO%2Blight%2Bcube&qid=1592967810&sr=8-2&th=1) and replaced their internals with our hardware. -- Raspberry Pi Model 3b+ (but any Raspberry Pi with Wifi capability should work) +- Raspberry Pi 3 Model B+ (but any Raspberry Pi with Wi-Fi capability should work) - [USB NFC readers](https://www.amazon.com/gp/product/B07Q5KXM6J/ref=ppx_yo_dt_b_asin_title_o06_s00?ie=UTF8&psc=1). These emulate a keyboard -- when an NFC badge is scanned onto them, they 'type' its ID into whatever they're connected to. - **PLEASE** make note of the model: if that link isn't dead, you'll see it links to a '14H' reader. '14H' (or '14D') is required to get the specificity necessary to distinguish between the NFC badge IDs: these readers read the most significant bit first, and since the card IDs are assigned sequentially this means that most of them have the same first 8-10 hex digits. You are in for much pain if you do not purchase the correct readers. -- Microusb battery pack. Best to get flat ones. +- Micro-USB battery pack. Best to get flat ones. - *Optionally*: LEDs ### Hardware: Future Considerations -- Raspberry Pi's are certainly overkill for this application. Since the boxes only need to make a single web request, a simpler IoT board (eg. ESP8266 or ESP32) would work just as well, consume far less power, and cost an order of magnitude less. - - As a corollary, "PiControl" is probably a bad name for this system as pretty much all of the logic is hardware-agnostic. Even the small Python script run on the Pi could probably run on a much simpler microcontroller (with a couple modifications) through Micropython. -- The keyboard emulation NFC readers were used because Katz (the author of this doc) had never touched hardware in his life and thus couldn't figure out how to use the [an actual breakout board](https://www.adafruit.com/product/364). In the first week of CS107e, he realized that he was connecting the board's TX and RX pins to the Pi's TX and RX pins (respectively). He has now learned that TX == "transmit" and RX == "receive" and thus TX on one board should be connected to RX on the other and vice versa. If you ever see Katz, feel free to chastise him for his foolishness. +- Raspberry Pi's are certainly overkill for this application. Since the boxes only need to make a single web request, a simpler IoT board (e.g. ESP8266 or ESP32) would work just as well, consume far less power, and cost an order of magnitude less. + - As a corollary, "PiControl" is probably a bad name for this system as pretty much all of the logic is hardware-agnostic. Even the small Python script run on the Pi could probably run on a much simpler microcontroller (with a couple modifications) through MicroPython. +- The keyboard emulation NFC readers were used because Katz (the author of this doc) had never touched hardware in his life and thus couldn't figure out how to use [an actual breakout board](https://www.adafruit.com/product/364). In the first week of CS107E, he realized that he was connecting the board's TX and RX pins to the Pi's TX and RX pins (respectively). He has now learned that TX == "transmit" and RX == "receive" and thus TX on one board should be connected to RX on the other and vice versa. If you ever see Katz, feel free to chastise him for his foolishness. ## Software ### On the Pi -The script run on the Pi can be found at https://github.com/MYKatz/PiControl. If you're using the aforementioned USB NFC readers, you should be running 'read_keyboard.py'. +The script run on the Pi can be found at [https://github.com/MYKatz/PiControl](https://github.com/MYKatz/PiControl). If you're using the aforementioned USB NFC readers, you should be running 'read_keyboard.py'. -The script is very simple: upon receiving input from the NFC reader (a card's ID), it sends that to a specified API endpoint. +The script is very simple: upon receiving input from the NFC reader (a card's ID), it sends that card ID to a specified API endpoint over HTTP. #### OS and dependencies -We used a standard install of Raspbian. You will need to configure the Pi to connect to Wifi -- there are many guides online to do this, such as [this one](https://raspberrypihq.com/how-to-connect-your-raspberry-pi-to-wifi/). +We used a standard install of Raspbian. You will need to configure the Pi to connect to Wi-Fi -- there are many guides online to do this, such as [this one](https://raspberrypihq.com/how-to-connect-your-raspberry-pi-to-wifi/). -An installation of Python 3.7 should include all of the necessary dependencies except for [Requests](https://requests.readthedocs.io/en/master/). A 'pip3 install requests' should work, provided you're connected to the internet. +An installation of Python 3.7 should include all of the necessary dependencies except for [requests](https://requests.readthedocs.io/en/master/). A 'pip3 install requests' should work, provided you're connected to the internet. ### Web App @@ -49,7 +49,7 @@ When the script on a Pi is ran for the first time, the Pi is registered with Pic #### Eventive Integration -PiControl works by scanning NFC IDs into events on Eventive, which does the heavy lifting matching these IDs to hackers. If you're going to use Eventive (and you probably should, it's great!) then remember to update the EVENTIVE_API_KEY environment variable and change the eventive API link in the code (which is currently hard-coded.. oops!) +PiControl works by scanning NFC IDs into events on [Eventive](https://eventive.org/), which does the heavy lifting matching these IDs to hackers. If you're going to use Eventive (and you probably should, it's great!) then remember to update the EVENTIVE_API_KEY environment variable and change the eventive API link in the code (which is currently hard-coded.. oops!) #### Environment Variables @@ -57,7 +57,7 @@ PiControl works by scanning NFC IDs into events on Eventive, which does the heav DATABASE_URL= /* postgresql uri string */ EVENTIVE_API_KEY= GIN_MODE=release /* either 'debug' or 'release' */ -PASSWORD= +PASSWORD=/* password required to access web app */ ``` @@ -67,11 +67,11 @@ PASSWORD= - Run `go get -u github.com/gin-gonic/gin github.com/joho/godotenv github.com/lib/pq` - Run `npm run dev-start` -Pushing and pulling to docker: https://ropenscilabs.github.io/r-docker-tutorial/04-Dockerhub.html +Pushing and pulling to docker: [https://ropenscilabs.github.io/r-docker-tutorial/04-Dockerhub.html](https://ropenscilabs.github.io/r-docker-tutorial/04-Dockerhub.html) #### Installation - Build using the dockerfile - Get the build onto your server - create .env file -- $ sudo docker run -d -t --env-file=".env" -p 80:80 [container id] \ No newline at end of file +- $ sudo docker run -d -t --env-file=".env" -p 80:80 [container id] From b0e18ea43761436e8daf1e918fadec9a6f17839d Mon Sep 17 00:00:00 2001 From: Katz Date: Wed, 24 Jun 2020 20:30:09 -0700 Subject: [PATCH 3/3] Update Picontrol.md --- docs/picontrol.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/picontrol.md b/docs/picontrol.md index 62f667e..f073abe 100644 --- a/docs/picontrol.md +++ b/docs/picontrol.md @@ -37,7 +37,11 @@ The script is very simple: upon receiving input from the NFC reader (a card's ID We used a standard install of Raspbian. You will need to configure the Pi to connect to Wifi -- there are many guides online to do this, such as [this one](https://raspberrypihq.com/how-to-connect-your-raspberry-pi-to-wifi/). -An installation of Python 3.7 should include all of the necessary dependencies except for [Requests](https://requests.readthedocs.io/en/master/). A 'pip3 install requests' should work, provided you're connected to the internet. +An installation of Python 3.7 should include all of the necessary dependencies except for [Requests](https://requests.readthedocs.io/en/master/). SSH'ing into the Pi and running 'pip3 install requests' should work, provided you're connected to the internet. + +#### Changing the Pi's Password + +Since hackers are going to be connected to the same network as the Pis, they will be able to trivially gain root access to the Pis if the default password is kept. Run the 'passwd' command while SSH'ed into the Pi; you'll be prompted for the default password ("raspberry" is the default) and then you can set your own. ### Web App @@ -63,7 +67,6 @@ PASSWORD= #### Development Set-up -- Set "homepage" in package.json to the url you want. - Run `go get -u github.com/gin-gonic/gin github.com/joho/godotenv github.com/lib/pq` - Run `npm run dev-start`