doorlock/readme.md

156 lines
4.2 KiB
Markdown
Raw Normal View History

2018-03-03 21:28:55 +00:00
# Chimera Doorlock
> A Tessel powered RFID doorlock for the space, interfacing with Cobot
## Technical Overview
2018-03-04 22:37:03 +00:00
The RFID doorlock consists of a few components that allow us to have a offline capable, yet up-to-date list of member's RFID cards:
* Tessel microcontroller powered by node.js
* USB RFID reader (125khz)
* SD card for storing RFID numbers
* OLED display
* 12v industrial door latch (default locked)
* Software to fetch cards, display messages and do validation and open the door
2018-03-04 22:44:40 +00:00
Currently, we are using [Cobot][cobot] to manage our membership as well as RFID card numbers (checkin tokens in Cobot parlance).
2018-03-04 22:43:24 +00:00
Eventually, we can remove Cobot and swap it with our own service if we desire.
2018-03-04 22:38:54 +00:00
#### Tessel Microcontroller
2018-03-04 22:38:24 +00:00
2018-03-04 22:44:40 +00:00
The doorlock consists of a [Tessel][tessel] microcontroller powered by node.js (JavaScript).
2018-03-04 22:43:24 +00:00
#### USB SD Card List
The doorlock has an attached USB adapter with an SD card to store the member's cards (in `json` format).
2018-03-04 22:38:24 +00:00
2018-03-04 22:38:54 +00:00
#### USB RFID Reader
2018-03-04 22:38:24 +00:00
A USB powered RFID card reader (125khz) is plugged into the other Tessel USB port. This reader behaves like a keyboard; when a card is scanned it sends a string of card numbers as keys with a newline character.
The application listens for card scan events and when one if found, it looks the card number up in a local database (the above mentioned `json` file). If it finds a card, it opens the door, if not it shows an error message.
2018-03-04 22:38:54 +00:00
#### Door Latch
2018-03-04 22:38:24 +00:00
2018-03-04 22:46:24 +00:00
To open the door, we use a relay (or optionally a TIP120 transistor) which powers a [12v door latch][latch]. If no power is sent to the door latch, it remains locked. When it gets a 12v current it opens and allows the member entry.
2018-03-04 22:38:54 +00:00
#### OLED Display
2018-03-04 22:38:24 +00:00
2018-03-04 22:41:54 +00:00
Whether a success or failure, we show details on an attached OLED display as well as when the card list updates or other unexpected issues.
2018-03-04 22:42:24 +00:00
#### RFID Card Sync
2018-03-04 22:38:24 +00:00
When the device first turns on it connects to WiFi and then fetches all the member RFID cards from the Cobot checkin token API and then updates the `json` card file. It completely overwrites the existing list of cards. If there is a failure getting the cards, we keep the original card list as a fallback.
2018-03-04 22:41:54 +00:00
We periodically sync this list every few minutes (configurable).
#### Access Log
We log every door open event so we can keep and eye on usage. We log an entry containing the member name, datetime and RFID card number in a `json` file. This list is sent to Cobot periodically so we can create a "checkin" for a member. Once the list is pushed successfully we clear out the file.
2018-03-03 21:28:55 +00:00
## Development
First, follow the [start guide][start] on [Tessel.io][tessel].
2018-03-03 21:28:55 +00:00
Next, install the correct version of node using nvm:
2018-03-03 21:28:55 +00:00
```bash
2018-03-03 21:30:38 +00:00
nvm install
nvm use
npm install
2018-03-03 21:28:55 +00:00
```
2018-03-03 21:30:38 +00:00
Now install `t2-cli` globally:
2018-03-03 21:28:55 +00:00
```bash
2018-03-03 21:30:38 +00:00
npm install -g t2-cli
2018-03-03 21:28:55 +00:00
```
2018-03-03 21:30:38 +00:00
Plug your Tessel in.
2018-03-03 21:28:55 +00:00
Now you can deploy to your connected Tessel device:
```bash
npm run deploy
2018-03-03 21:28:55 +00:00
```
2018-03-04 22:47:25 +00:00
For local development, you can run:
```bash
npm start
```
...which will run the application locally as well as run the test suite, watching for changes.
2018-03-04 22:54:11 +00:00
## Testing
2018-03-03 21:28:55 +00:00
We use [Jest][jest] to do testing of the core code in the library. Make sure to write tests for new code or update tests on existing code as needed. Test files are next to their source file named with a `.test.js` extension.
2018-03-04 22:46:24 +00:00
Run tests once:
2018-03-03 21:28:55 +00:00
2018-03-04 22:46:24 +00:00
```bash
npm test
```
Run tests watching for changes:
```bash
npm run watch-test
```
2018-03-03 21:28:55 +00:00
2018-03-04 22:54:11 +00:00
## Useful Details
2018-03-03 21:28:55 +00:00
### Useful Commands
```bash
# List devices
t2 list
# Update Tessel
t2 update
# Deploy code
t2 push index.js
# Clear code
t2 erase
# Connect to WiFi
t2 wifi -n network-name -p "some password"
2018-03-03 21:28:55 +00:00
# Create access point and server
t2 ap -n doorlock
```
### Networking
To find the IP address of your Tessel, download the iOS app Fing and look for a device on your network called `doorlock`.
2018-03-03 21:28:55 +00:00
### USB Storage
* Make sure to format micro SD to be FAT32!
2018-03-03 21:28:55 +00:00
2018-03-04 22:54:11 +00:00
## Contributing
Contributions welcome!
Want to contribute? Submit a Pull Request with your changes!
Using this in your own project? Let us know by creating an issue in Github!
## Credits
Developed by [Dana Woodman][dana] © 2018.
## License
MIT
2018-03-04 22:44:40 +00:00
[cobot]: https://www.cobot.me/
2018-03-04 22:54:11 +00:00
[dana]: http://danawoodman.com
2018-03-03 21:30:38 +00:00
[jest]: https://facebook.github.io/jest
2018-03-04 22:46:24 +00:00
[latch]: https://www.amazon.com/gp/product/B00V45GWTI
2018-03-03 21:28:55 +00:00
[start]: http://tessel.github.io/t2-start
[tessel]: http://tessel.io