From 9d32fc64bcadc849a447c244acacdbb8ad615fb1 Mon Sep 17 00:00:00 2001 From: Tom Haines Date: Thu, 9 Jul 2020 12:19:46 +0100 Subject: [PATCH 1/4] Began a getting started guide --- getting_started.md | 102 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 getting_started.md diff --git a/getting_started.md b/getting_started.md new file mode 100644 index 0000000..b147658 --- /dev/null +++ b/getting_started.md @@ -0,0 +1,102 @@ +
+ +# Getting Started with `dwyl/smart-home-*` +Set up a development or production environment of the Dwyl smart home system. + +____ + +
+ +**This document is a work in progress, +please file an issue for any problems you find setting up the +development environment** + +---- + +### What? +This is a getting started guide for the Dwyl smart home system. +It contains everything you need to set up your own system; +either for development or production. + +It contains no infomation on any of the protocols used or how the system works, +this can be found here: ***TODO: Design documentation*** + +### Why? +It is a complex system with lots of moving parts, +and unfortunately setting it up requires some time and configuration. +We've tried to make this as simple as possible, with only +two repositories needed to make a working system. +You also need to make sure you have compatible hardware, +found in the "prerequisites" section. + +---- + +## Prerequisites + +#### Required Knowledge + +You should be able to go through this guide with no previous knowledge of Iot, +Elixir, or Nerves. +However, we do recommened you go though our [Learn Nerves](https://github.com/dwyl/learn-nerves) +tutorial first so you know *why* things are happening and have Nerves setup +on your computer. +Some knowledge of wiring up GPIO headers on a Raspberry Pi would also +go a long way. + +#### Required hardware +Although we have no "hard" requirements on the specifics - +(it should work on any [Nerves compatible](https://hexdocs.pm/nerves/targets.html) +hardware) - this is the hardware the systems been designed for and will work +best on. + +| Hardware | Notes | +|----------|--------| +Raspberry Pi 3+ / Zero | Or anything better with WiFi support +PN532 Development board | Find on with UART support +Necessary Connectors | You'll need at least 4 female-female wires 1 +Hub Server | Anything that can run a server, another Raspberry Pi, or I used my laptop for development. + +1 : You can also use a breadboard with normal F-to-M jumper wires +https://imgur.com/a/OQK8zMO + + +#### Required Software + +You'll need Elixir and Nerves setup on your computer. +If you don't have this, please follow the first part of our +[Learn Nerves](https://github.com/dwyl/learn-nerves) tutorial. + +API Development software. Our hub currently does not have a GUI, +only a REST API. +I recommend using [Insomnia Core](https://insomnia.rest/) as there's a +workspace already setup in the Hub repo. + +You'll also need a Dwyl API key, follow the instructions here: +https://github.com/dwyl/auth_plug#2-get-your-auth_api_key- + +## Setup + +1. Clone the necessary repositories: + + git clone https://github.com/dwyl/smart-home-auth-server + git clone https://github.com/dwyl/smart-home-firmware + +2. If you haven't yet, set your DWYL_API_KEY/AUTH_API_KEY + + export AUTH_API_KEY= + +3. Wire up the Raspberry Pi to the PN532 board over UART + + [GPIO Diagram](https://pinout.xyz/pinout/uart) + + | Pi | PN532 | + |--------------|-------| + 5v | 5v + Ground | Ground + TXD (GPIO 14) | RX + RXD (GPIO 15) | TX + +Use the linked GPIO diagram to work out which pins which. Your development +board should have pins labelled. + + From b45d98fed37df71d847ebbc60673bfe3bf1201eb Mon Sep 17 00:00:00 2001 From: Tom Haines Date: Thu, 9 Jul 2020 12:21:00 +0100 Subject: [PATCH 2/4] Added initial connection --- getting_started.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/getting_started.md b/getting_started.md index b147658..2408bf6 100644 --- a/getting_started.md +++ b/getting_started.md @@ -66,6 +66,8 @@ You'll need Elixir and Nerves setup on your computer. If you don't have this, please follow the first part of our [Learn Nerves](https://github.com/dwyl/learn-nerves) tutorial. +You'll also need postgres running where your hosting the hub server. + API Development software. Our hub currently does not have a GUI, only a REST API. I recommend using [Insomnia Core](https://insomnia.rest/) as there's a @@ -99,4 +101,74 @@ https://github.com/dwyl/auth_plug#2-get-your-auth_api_key- Use the linked GPIO diagram to work out which pins which. Your development board should have pins labelled. +### Setup the Hub server +Change directory into the hub server folder: + + cd smart-home-auth-server/ + +and then setup and run the server + + mix setup + mix phx.server + +This should be all you have to do. + + +### Setup REST API developent + +**This is a pain, we need to fix this** + +Visit https://localhost:4000/api/v0/users in your browser. +This should trigger an Authentication flow and redirect you to the +Dwyl auth site. +Log in and wait for you to be redirected back. + +Look in the URL, you should see a long string of letters after `?jwt=`. +Copy this. + +Open Insomnia, go to Get User on the sidebar. + - Click Auth dropdown + - Bearer Token + - Paste the token you copied into `token` + - Press send, this should apply a global auth cookie + +This should only have to be done once. + +### Install the Lock firmware + +Navigate to the firmware repository, e.g. + + cd ../smart-home-firmware + +Change the `:smart_home_firmware, :hub` config value in both +`config/config.exs` and `config/target.exs` to the IP and port of +the hub server you setup in the previous steps. + +On macOS, you can option-click your network connection to get your IP, and the +port will default to 4000 on Phoenix. + +```elixir +config :smart_home_firmware, + hub: "192.168.0.14:4000" +``` + +Then create a firmware with your WiFi credentials and burn it to an SD card. +If your not using WiFi, skip these environment vars, +it will still connect over Ethernet automatically: + +``` +NERVES_NETWORK_SSID= NERVES_NETWORK_PSK= mix firmware.burn +``` + +You could also save these to a `.env` file to avoid writing out every time - +I just keep mine in terminal history with `fish`. + +Insert the SD card into the Pi and boot it up. + +After around a minute, if everything works, you should see a message similar to +``` +[info] lock-8650 has come online +``` +appear in your hub servers logs. This means everything is configured correctly, +and the locks can correctly connect to the hub server. \ No newline at end of file From 830c37a36752ded8c2917ed935e12872b71171e0 Mon Sep 17 00:00:00 2001 From: Tom Haines Date: Fri, 10 Jul 2020 16:48:40 +0100 Subject: [PATCH 3/4] Include inline image Co-authored-by: Nelson <194400+nelsonic@users.noreply.github.com> --- getting_started.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/getting_started.md b/getting_started.md index 2408bf6..42a6c70 100644 --- a/getting_started.md +++ b/getting_started.md @@ -57,7 +57,7 @@ Necessary Connectors | You'll need at least 4 female-female wires 1 Hub Server | Anything that can run a server, another Raspberry Pi, or I used my laptop for development. 1 : You can also use a breadboard with normal F-to-M jumper wires -https://imgur.com/a/OQK8zMO +![NFC-Reader-Wired-using-Breadboard](https://i.imgur.com/g7JqsfO.png) #### Required Software @@ -171,4 +171,4 @@ After around a minute, if everything works, you should see a message similar to ``` appear in your hub servers logs. This means everything is configured correctly, -and the locks can correctly connect to the hub server. \ No newline at end of file +and the locks can correctly connect to the hub server. From 8575ea31dd613e65b7083496730b5bf55b1130f9 Mon Sep 17 00:00:00 2001 From: Tom Haines Date: Fri, 10 Jul 2020 16:49:15 +0100 Subject: [PATCH 4/4] Expand UART acronymn Co-authored-by: Nelson <194400+nelsonic@users.noreply.github.com> --- getting_started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting_started.md b/getting_started.md index 42a6c70..00f87b4 100644 --- a/getting_started.md +++ b/getting_started.md @@ -87,7 +87,7 @@ https://github.com/dwyl/auth_plug#2-get-your-auth_api_key- export AUTH_API_KEY= -3. Wire up the Raspberry Pi to the PN532 board over UART +3. Wire up the Raspberry Pi to the PN532 board over Universal Asynchronous Receiver/Transmitter (UART) protocol [GPIO Diagram](https://pinout.xyz/pinout/uart)