diff --git a/README.md b/README.md index 9e8c2ce..997ecb1 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,19 @@ have cited about the other parties where taken from their respective websites. I have, also, applied minor editing in places to help readability - in the context of this file. Please use the links listed below for the original/official version of the sourced material. Craig -is the author of the software in this repository.** +is the author of the software for the 'Personal Flash in Real-Time' +project and its technical documentation** + +This documentation is not targetted at the general public. It is for +those with experience in the following: + +- sofware development (ideally Python) +- Linux (in general) +- Amazon Web Services (virtual machines and SSH) +- Raspberry Pi +- Nginx +- electronics (to a basic level) +- .Net and UWP (for Eyes and Ears project only) ## Return to Ritherdon Overview @@ -42,50 +54,35 @@ They were set up in 1946, by Royal Charter, to champion and develop art and culture across the country. They are governed by an Executive Board and National and Area Councils. -- [Arts Council England's Royal - Charter](https://www.artscouncil.org.uk/sites/default/files/download-file/Consolidated_Royal_Charter_2013.pdf) +- [Arts Council England's Royal Charter](https://www.artscouncil.org.uk/sites/default/files/download-file/Consolidated_Royal_Charter_2013.pdf) ## Overview of Return to Ritherdon Docs (rtr-docs) -This repository houses the documentation for the, at the time of -writing, *unnamed project* which is one project within the much bigger -**Return to Ritherdon** project . The contents of the *unnamed -project* consists of four smaller projects which are: +This repository houses the documentation for the 'Personal Flash in +Real-Time' project which is one project within the much bigger project +called **Return to Ritherdon**. The contents of the 'Personal Flash in +Real-Time' consists of three smaller projects (and two secondary) +which are: -- [Light - Meter](https://git.abbether.net/return-to-ritherdon/light-meter) +- [Light Meter](https://git.abbether.net/return-to-ritherdon/light-meter) - [Relay](https://git.abbether.net/return-to-ritherdon/relay) - [Midpoint](https://git.abbether.net/return-to-ritherdon/relay) -- [Eyes and - Ears](https://git.abbether.net/return-to-ritherdon/eyes-and-ears) - (this is a non-essential project and excluded from the diagrams - below to keep things simple -- at this introductory stage) - -![Main Project Overview](attachments/return-to-ritherdon-project-overview.png) -As you can see, 'Artwork 1' is what this repository is for, which is -just one artwork/project within the much bigger 'Return to Ritherdon' -project. Within 'Artwork 1' is three smaller projects (listed and -linked above). Below is a quick summary of how the three projects -operate. (Please refer to the doc. files within this repo. for more -in-depth breakdowns of how this all works.) +The secondary projects are: -![main-proj-architecture](attachments/main-proj-architecture.png) +- [Eyes and Ears](https://git.abbether.net/return-to-ritherdon/eyes-and-ears) +- [Light Wave](https://git.abbether.net/return-to-ritherdon/light-wave) -### Goals of This Repository +![Main Project Overview](attachments/return-to-ritherdon-project-overview.png) -The intention with this repository is to create a place which tracks -all the documentation changes across the *unnamed* project in one -place. This should help people whom are not exposed to the project in -any sustained way have a single place they can go to for information -about the projects within *unnamed*. With that said, **the -documentation hosted here is for technicians and 'back of house' -staff**. The content within this repository does not prioritise -general public use. +As you can see, 'Personal Flash in Real-Time' is what this repository +is for, which is just one artwork/project within the much bigger +'Return to Ritherdon' project. Within 'Personal Flash in Real-Time' is +three smaller projects (listed and linked above). Below is a quick +summary of how the three projects operate. (Please refer to the +doc. files within this repo. for more in-depth breakdowns of how this +all works.) -You can read the documentation in this repository in two ways: +![main-proj-architecture](attachments/main-proj-architecture.png) -1. read the raw markdown (.md) files within the project folders in - this repository, or; -2. download a 'Released' version and read that (as a .pdf). diff --git a/attachments/main-proj-architecture.dot b/attachments/main-proj-architecture.dot new file mode 100644 index 0000000..6c961a8 --- /dev/null +++ b/attachments/main-proj-architecture.dot @@ -0,0 +1,14 @@ +digraph overview { + node [fontname = Arial]; + l1 -> server; + l2 -> server; + server -> r1; + server -> r2; + r1 -> server; + r2 -> server; + l1 [label = "Light Meter 1", color = lightblue, style = filled]; + l2 [label = "Light Meter 2", color = orange, style = filled]; + r1 [label = "Relay 1", color = lightblue, style = filled]; + r2 [label = "Relay 2", color = orange, style = filled ]; + server [label = "Midpoint (Server)"]; +} diff --git a/attachments/main-proj-architecture.png b/attachments/main-proj-architecture.png index 2bd3b31..dc9477f 100644 Binary files a/attachments/main-proj-architecture.png and b/attachments/main-proj-architecture.png differ diff --git a/attachments/return-to-ritherdon-project-overview.dot b/attachments/return-to-ritherdon-project-overview.dot new file mode 100644 index 0000000..4b8d1c3 --- /dev/null +++ b/attachments/return-to-ritherdon-project-overview.dot @@ -0,0 +1,29 @@ +digraph overview { + fontname = Arial; + node [fontname = Arial]; + label = "Return to Ritherdon"; + labelloc = top; + style = filled; + color = lightgrey; + fontsize = 20; + subgraph cluster0 { + style = filled; + node [style = filled, color = white]; + color = lightblue; + label = "Personal Flash in Real-Time (I.E. 'Artwork 1')"; + fontsize = 16; + Light; + Midpoint; + Relay; + } + subgraph cluster1 { + label = "The other artworks in the exhibiton/project..."; + fontsize = 16; + color = white; + style = filled; + a5 [label = "Artwork 5"]; + a4 [label = "Artwork 4"]; + a3 [label = "Artwork 3"]; + a2 [label = "Artwork 2"]; + } +} diff --git a/attachments/return-to-ritherdon-project-overview.png b/attachments/return-to-ritherdon-project-overview.png index e22e2b7..72c6319 100644 Binary files a/attachments/return-to-ritherdon-project-overview.png and b/attachments/return-to-ritherdon-project-overview.png differ diff --git a/eyes-and-ears/attachments/app-internals.dot b/eyes-and-ears/attachments/app-internals.dot new file mode 100644 index 0000000..ab56768 --- /dev/null +++ b/eyes-and-ears/attachments/app-internals.dot @@ -0,0 +1,17 @@ +digraph overview { + fontname = Arial; + labelloc = t; + label = "Eyes and Ears"; + fontsize = 20; + node [fontname = Arial]; + MainPage -> ViewModel -> Services; + ViewModel -> MainPage; + Services -> ViewModel; + MainPage -> Services; + Services -> MainPage; + Models -> ViewModel; + Models -> MainPage; + Models -> Services; + MainPage [style = filled, color = lightblue, label="MainPage (View and Code-Behind)"]; + ViewModel [label = "ViewModels/MainPageVM"]; +} diff --git a/eyes-and-ears/attachments/app-internals.png b/eyes-and-ears/attachments/app-internals.png new file mode 100644 index 0000000..0ce03af Binary files /dev/null and b/eyes-and-ears/attachments/app-internals.png differ diff --git a/eyes-and-ears/attachments/eyes-and-ears-screenshot-1.png b/eyes-and-ears/attachments/eyes-and-ears-screenshot-1.png new file mode 100644 index 0000000..3aca99b Binary files /dev/null and b/eyes-and-ears/attachments/eyes-and-ears-screenshot-1.png differ diff --git a/eyes-and-ears/attachments/eyes-and-ears-screenshot-2.png b/eyes-and-ears/attachments/eyes-and-ears-screenshot-2.png new file mode 100644 index 0000000..d6b3547 Binary files /dev/null and b/eyes-and-ears/attachments/eyes-and-ears-screenshot-2.png differ diff --git a/eyes-and-ears/attachments/gui-breakdown.png b/eyes-and-ears/attachments/gui-breakdown.png new file mode 100644 index 0000000..9bc6e2e Binary files /dev/null and b/eyes-and-ears/attachments/gui-breakdown.png differ diff --git a/eyes-and-ears/attachments/system-overview.dot b/eyes-and-ears/attachments/system-overview.dot new file mode 100644 index 0000000..cd6a62e --- /dev/null +++ b/eyes-and-ears/attachments/system-overview.dot @@ -0,0 +1,21 @@ +digraph overview { + subgraph cluster0 { + label = "Main System"; + fontname=Arial; + fontsize=20; + node [style=filled,color=white,fontname=Arial]; + style=filled; + color=lightblue; + l1 -> Server -> r1; + l2 -> Server -> r2; + r1 -> Server; + r2 -> Server; + l1 [label = "Light Meter 1"]; + l2 [label = "Light Meter 2"]; + r1 [label = "Relay 1"]; + r2 [label = "Relay 2"]; + } + e -> Server; + Server -> e; + e [label = "Eyes and Ears",fontname=Arial;]; +} diff --git a/eyes-and-ears/attachments/system-overview.png b/eyes-and-ears/attachments/system-overview.png new file mode 100644 index 0000000..c942e47 Binary files /dev/null and b/eyes-and-ears/attachments/system-overview.png differ diff --git a/eyes-and-ears/rtr-eyes-and-ears.md b/eyes-and-ears/rtr-eyes-and-ears.md index e69de29..4cbc7d5 100644 --- a/eyes-and-ears/rtr-eyes-and-ears.md +++ b/eyes-and-ears/rtr-eyes-and-ears.md @@ -0,0 +1,154 @@ +# Return to Ritherdon: Eyes and Ears + +Eyes and Ears is a Windows UWP 'Dashboard App.' which monitors the +overall artwork, 'Personal Flash in Real-Time' -- which is one of +several artworks in the 'Return to Ritherdon' project. For more +information on the 'Return to Ritherdon' project, please use the +following link: + +- [Return to Ritherdon Overview](https://git.abbether.net/return-to-ritherdon/rtr-docs) + +![Screenshot 1](./attachments/eyes-and-ears-screenshot-1.png) + +![Screenshot 2](./attachments/eyes-and-ears-screenshot-2.png) + +## Overview of Eyes and Ears Fits into the 'Personal Flash in Real-Time' System + +For the purpose of this documentation, I will refer to 'Personal Flash +in Real-Time' as a 'system' instead of an 'artwork'. The reason why is +becaues of the context we are viewing the various (sub-)projects and +their components in. + +First of all, Eyes and Ears is not an essential part of the system. It +is a nice to have. There are three smaller projects which combine to +create the whole 'Personal Flash in Real-Time' system. On top of that, +they reside in different places across the U.K. which makes it +difficult to see what state the whole system is in at any one +moment. It is not unsurmountable but this dashboard app. helps. + +![System Overview](./attachments/system-overview.png) + +For more information on the other parts of the system, use the following +links: + +- [Light Meter Code](https://git.abbether.net/return-to-ritherdon/light-meter) +- [Light Meter Documentation](https://git.abbether.net/return-to-ritherdon/rtr-docs/src/branch/master/light-meter) +- [Relay Code](https://git.abbether.net/return-to-ritherdon/relay) +- [Relay Documentation](https://git.abbether.net/return-to-ritherdon/rtr-docs/src/branch/master/relay) +- [Midpoint Code](https://git.abbether.net/return-to-ritherdon/midpoint) +- [Midpoint Documentation](https://git.abbether.net/return-to-ritherdon/rtr-docs/src/branch/master/midpoint) + +## Technology Overview + +Because of the nature of 'Personal Flash in Real-Time', Eyes and Ears +has no long term maintainence concerns. So, the code is a bit of a +mess. The biggest mess is the lack of seperation between the code in +the view (`MainPage.cs`) and the view-model (`MainPageVM.cs`). If +anything, I think it would be easier to re-write Eyes and Ears than +look to add new features. + +Eyes and Ears in written in C# and the Universal Windows Platform +(UWP) and targets Windows 10. I should point out **Microsoft is moving +away from UWP so you should view this application as obsolete**. + +- [Universal Windows Platform (UWP)](https://docs.microsoft.com/en-us/windows/uwp/) +- [Article on Microsoft dropping UWP](https://www.techradar.com/news/microsoft-is-finally-dropping-uwp-app-support-windows-app-sdk-heres-why) + +The project's structure is a typical UWP one. There are a lot of files +you do not need to touch so I have highlighted the files/directories +you will spend the most time in with `(AREA OF INTEREST)`. + +```shell +./src + └── EyesAndEars.UWP + ├── EyesAndEars.UWP + │   ├── AppPackages + │   ├── App.xaml + │   ├── App.xaml.cs + │   ├── Assets + │   ├── bin + │   ├── BundleArtifacts + │   ├── EyesAndEars.UWP.csproj + │   ├── EyesAndEars.UWP.csproj.user + │   ├── EyesAndEars.UWP_TemporaryKey.pfx + │   ├── images + │   ├── MainPage.xaml <------ (AREA OF INTEREST) + │   ├── MainPage.xaml.cs <--- (AREA OF INTEREST) + │   ├── Models <------------- (AREA OF INTEREST) + │   ├── obj + │   ├── Package.appxmanifest + │   ├── Properties + │   ├── Services <----------- (AREA OF INTEREST) + │   └── ViewModels <--------- (AREA OF INTEREST) + └── EyesAndEars.UWP.sln +``` + +Below is a diagram showing how the various pieces fit together. The +`Models`, `ViewModel` and `Services` sections are the +directories. There are further files in them. I should point out there +is only one ViewModel called `MainPageVM.cs` which binds to `MainPage.cs`. + +![App-Internals](./attachments/app-internals.png) + +## How-To Use Eyes and Ears + +The first time you start Eyes and Ears, you need to input the URL to +the server part of the system (MidPoint). You do this by entering it +in the URL-bar (3) at the bottom of the screen and then press the +'Save' button (6). For all intents and purposes, that is all you need +to do. The rest of the features are secondary and you can get away +with not ever using them. + +For more information on the other parts of the system, use the following +links: + +- [Light Meter Code](https://git.abbether.net/return-to-ritherdon/light-meter) +- [Light Meter Documentation](https://git.abbether.net/return-to-ritherdon/rtr-docs/src/branch/master/light-meter) +- [Relay Code](https://git.abbether.net/return-to-ritherdon/relay) +- [Relay Documentation](https://git.abbether.net/return-to-ritherdon/rtr-docs/src/branch/master/relay) +- [Midpoint Code](https://git.abbether.net/return-to-ritherdon/midpoint) +- [Midpoint Documentation](https://git.abbether.net/return-to-ritherdon/rtr-docs/src/branch/master/midpoint) + +The URL has changed throughout the course of developing the whole +system ('Personal Flash in Real-Time'). So, you will need to confirm +the URL is correct which means you will need to speak to whomever is +running the server (Midpoint) part of the system. + +![GUI-Breakdown](./attachments/gui-breakdown.png) + +1. Log Toggle (toggle debug logs (6) on/off) +2. Info. button (artist's website) +3. URL-Bar (to connect to (Midpoint) server +4. Play/Stop Button (stop and start updating system status) +5. Save Button (writes the URL to disk for future use) +6. Debug Logs (used to testing and you will probably never need to use + it) +7. Main Info. Area (displays the status of the various devices making + up the whole system) +8. Current Time (used to cross-reference the time-stamps of the + various status updates) + +When Eyes and Ears is running, the Main Info. (7) displays the +time-stamp of the latest event pushed to the server (Midpoint). The +main (biggest) numbers in `Factory 1` and `Factory 2` states the +latest light level reading taken from their respective +devices. `Gallery 1` and `Gallery 2` refers to when the devices are +either turned-on (and online) or turned-off (and offline as a +result). Refer to the Legend for the colour coded nature of the +various devices within the application itself. The 'Low Light' colour +refers to when the light meters (`Factory 1` and `Factory 2`) record +'negative light'. The reason why this happens is beyond the scope of +this documentation (and the Eyes and Ears application). + +# Installing Eyes and Ears + +The easiest way to install the program is by downloading a build in +the 'Releases' section on the main (I.E. code) repository: + +- [Eyes and Ears Releases Page](https://git.abbether.net/return-to-ritherdon/eyes-and-ears/releases) + +If you have Visual Studio, you can build from the source code either +by pressing `F5` and or using the `Publish` feature within Visual +Studio. I will not go into detail on how to do this becuase it is a +Visual Studio, .Net, C# and UWP specific concern -- which is outside +the scope of this documentation. diff --git a/health-and-safety/photosensitive_epilepsy.md b/health-and-safety/photosensitive_epilepsy.md index d5f3ff1..bf91813 100644 --- a/health-and-safety/photosensitive_epilepsy.md +++ b/health-and-safety/photosensitive_epilepsy.md @@ -1,7 +1,7 @@ # Return to Ritherdon: Photosensitive Epilepsy This document is part of the health and safety risk assessment for the -artworks *Personal Flash in Real Time (Ross)* and *Personal Flash in +artworks *Personal Flash in Real Time (Andy)* and *Personal Flash in Real Time (Tony)* which are part of the Return to Ritherdon exhibition. If you would like to know more about how the artwork and the exhibition, head to [Return to Ritherdon @@ -13,7 +13,7 @@ Oates](https://git.abbether.net/craig.oates). ## Summary of Assessment The amount of flashes the artworks ('*Personal Flash in Real Time -(Ross)*' and '*Personal Flash in Real Time (Tony)*') produce are not +(Andy)*' and '*Personal Flash in Real Time (Tony)*') produce are not of a high enough rate to cause a photosensitive epileptic seizure -- according to the referenced sources below ('between 3-30 hertz'). @@ -41,7 +41,7 @@ hertz, at most**. To expand on the second point, I have analysed and reviewed a days-worth of **live test** data, collected on the -**23/04/2021**. *Personal Flash in Real Time (Ross)* (the light meter +**23/04/2021**. *Personal Flash in Real Time (Andy)* (the light meter part of the artwork) took the light readings from **06:57 to 16:00** (approx. 9 hours). Also, the test was conducted under the intended environment and under real-world conditions. @@ -77,7 +77,7 @@ More information available at: ## How Risk Assessment Relates to the Return to Ritherdon Project -The artworks *Personal Flash in Real Time (Ross)* and *Personal Flash +The artworks *Personal Flash in Real Time (Andy)* and *Personal Flash in Real Time (Tony)* this document refers to are two artworks which are, in effect, one system and part of a much bigger project (called Return to Ritherdon). Within these two artworks are flashing @@ -237,7 +237,7 @@ the factory which this system monitors ('Light Meter 1' and 'Light Meter 2' in the diagram above) and each one has their own threshold to indicate when welding is occuring. For example, when the light level for 'Light Meter 1' goes above `39` (at time of writing), this -indicates a staff member (Ross) in the 'first' welding booth is +indicates a staff member (Andy) in the 'first' welding booth is welding which triggers the light to turn on in the gallery ('Gallery Light 1'). Throughout the course of the day (factory operating hours are 07:00-16:00), the system repeats this process and documents every diff --git a/light-meter/attachments/main-proj-architecture.dot b/light-meter/attachments/main-proj-architecture.dot new file mode 100644 index 0000000..c35cf62 --- /dev/null +++ b/light-meter/attachments/main-proj-architecture.dot @@ -0,0 +1,20 @@ +digraph overview { + node [fontname = Arial]; + subgraph cluster0 { + style = filled; + color = lightgrey; + l1; + l2; + } + l1 -> server; + l2 -> server; + server -> r1; + server -> r2; + r1 -> server; + r2 -> server; + l1 [label = "Light Meter 1", color = lightblue, style = filled]; + l2 [label = "Light Meter 2", color = orange, style = filled]; + r1 [label = "Relay 1", color = lightblue, style = filled]; + r2 [label = "Relay 2", color = orange, style = filled ]; + server [label = "Midpoint (Server)"]; +} diff --git a/light-meter/attachments/main-proj-architecture.png b/light-meter/attachments/main-proj-architecture.png index 2bd3b31..93ae2e8 100644 Binary files a/light-meter/attachments/main-proj-architecture.png and b/light-meter/attachments/main-proj-architecture.png differ diff --git a/light-meter/rtr-light-meter.md b/light-meter/rtr-light-meter.md index 8fb7c4e..a2d7fd6 100644 --- a/light-meter/rtr-light-meter.md +++ b/light-meter/rtr-light-meter.md @@ -1,76 +1,28 @@ # Return to Ritherdon: Light Meter -## Table of Contents +Light Meter is one of three smaller projects which make-up the +'Personal Flash in Real-Time' -- which is one artwork within the main +'Return to Ritherdon' project. You should view the three smaller +projects as one project. And, for the purpose of this documentation, I +will refer to 'Personal Flash in Real-Time' as a system instead of an +artwork. -To be added later... +For more information on the 'Return to Ritherdon' project, use the +following link: -## Return to Ritherdon: Project Overview +- [Return to Ritherdon Overview](https://git.abbether.net/return-to-ritherdon/rtr-docs) -**Disclosure: This document was written by [Craig -Oates](https://git.abbether.net/craig.oates) and all information I -have cited about the other parties where taken from their respective -websites. I have, also, applied minor editing in places to help -readability - in the context of this document. Please use the links listed -below for the original/official version of the sourced material. Craig -is the author of the software in this repository.** +### 'Personal Flash in Real-Time': Project Overview -## Return to Ritherdon Overview - -'Return to Ritherdon' is a two year residency at Ritherdon & Co Ltd, a -manufacturer of metal enclosures based in Darwen, Lancashire U.K. It -was devised by artist Nicola Ellis and funded by Arts Council England. - -- [Nicola Ellis](http://www.nicolaellis.com) -- [Ritherdon](https://www.ritherdon.co.uk/about-us/) -- [Arts Council England](https://www.artscouncil.org.uk/) - -### About the Artist: Nicola Ellis - -Nicola is interested in the properties, value, function and -circulation of materials. She has a current focus on metals and the -companies that work with them, her work draws on the visual and spoken -language of industry operations, fabrication and profiling -processes. The parameters for her sculpture, installation, drawings -and videos include relationships between people, businesses and -technology. - -### About the Manufacturer: Ritherdon - -Established in 1895, Ritherdon have been manufacturing a variety of -electrical enclosures and related products for many decades. A -combination of a passion for innovation with close working -relationships with their customers means that they are continually -developing and expanding their product ranges. - -### About: Arts Council England - -They were set up in 1946, by Royal Charter, to champion and develop -art and culture across the country. They are governed by an Executive -Board and National and Area Councils. - -- [Arts Council England's Royal - Charter](https://www.artscouncil.org.uk/sites/default/files/download-file/Consolidated_Royal_Charter_2013.pdf) - -## Light Meter: Project Overview - -Light Meter is one of three smaller projects which fall within the -Return to Ritherdon project. You should view the three smaller -projects as one project but, at the time of writing, the project does -not have a name. So, for the time being, I will refer to it as -'Artwork 1'. - -### 'Artwork 1': Project Overview - -The overall project ("Artwork 1" not 'Return to Ritherdon' or 'Light -Meter') consists of three separate/smaller projects. The names of the -smaller projects are a by-product of the software development -process. You should not view them as individual pieces within the -overall project. From an artwork point-of-view, "Artwork 1" is one -piece. The name of the software projects are 'Light Meter' (which is -this one), 'Midpoint' and 'Relay'. All three projects reside in their -own git repositories. You can find the other project's repositories at -the following links: +The overall system ('Personal Flash in Real-Time') consists of three +separate/smaller projects. You should not view them as individual +pieces within the overall project. From an artwork point-of-view, +'Personal Flash in Real-Time' is one piece. The name of the software +projects are 'Light Meter' (which is this one), 'Midpoint' and +'Relay'. All three projects reside in their own git repositories. You +can find the repositories at the following links: +- [Light Meter](https://git.abbether.net/return-to-ritherdon/light-meter) - [Mid-Point](https://git.abbether.net/return-to-ritherdon/midpoint) - [Relay](https://git.abbether.net/return-to-ritherdon/relay) @@ -151,12 +103,9 @@ website. **A good quality 2.5A power supply can be used if downstream USB peripherals consume less than 500mA in total.** -- [Raspberry Pi 4 Model B product - brief](https://static.raspberrypi.org/files/product-briefs/200521+Raspberry+Pi+4+Product+Brief.pdf) -- [Raspberry Pi 4 Model B schematic - diagrams](https://www.raspberrypi.org/documentation/hardware/raspberrypi/schematics/rpi_SCH_4b_4p0_reduced.pdf) -- [Raspberry Pi 4 Model B mechanical - drawing](https://www.raspberrypi.org/documentation/hardware/raspberrypi/mechanical/rpi_MECH_4b_4p0.pdf) +- [Raspberry Pi 4 Model B product brief](https://static.raspberrypi.org/files/product-briefs/200521+Raspberry+Pi+4+Product+Brief.pdf) +- [Raspberry Pi 4 Model B schematic diagrams](https://www.raspberrypi.org/documentation/hardware/raspberrypi/schematics/rpi_SCH_4b_4p0_reduced.pdf) +- [Raspberry Pi 4 Model B mechanical drawing](https://www.raspberrypi.org/documentation/hardware/raspberrypi/mechanical/rpi_MECH_4b_4p0.pdf) ## Project Set-Up @@ -195,8 +144,7 @@ work on the command-line (if you are using a "headless" version of Raspbian). If you are unsure how to connect to a router via wi-fi, use the following link to learn how: -- [Raspbian Wi-Fi - Tutorial](https://www.raspberrypi.org/documentation/configuration/wireless/wireless-cli.md) +- [Raspbian Wi-Fi Tutorial](https://www.raspberrypi.org/documentation/configuration/wireless/wireless-cli.md) The easiest way to do this is via the "raspi-config" file/command. You can access it by entering `sudo raspi-config` into the console and @@ -320,3 +268,31 @@ easier to test the bespoke shutdown procedure is working as intended. You can, also, adjust the time in the crontab or run the script by running the script like you normally would but I find them to be frustrating to do in this instance. + +## Running the Program + +You should not need to run the program manually (after you have set +everything up). With that said, you can make sure the software works +by running the following commands, + +```python +# This assumes you have followed the set-up steps above and you are +# not running the code in a virtual environment. + +# Adjust the path to match the location of the .py file. +python3 /home/rtrp/repos/light-meter/cli_meter.py +``` + +There is a GUI program which you can run which runs locally. I used +this for testing and probably have not used it since the very early +stages of developing this project. It basically displays the light +levels on a screen. This requires Raspbain (RaspberryPi OS) to have it +desktop environment installed. To run it, + +```python +# This assumes you have followed the set-up steps above and you are +# not running the code in a virtual environment. + +# Adjust the path to match the location of the .py file. +python3 /home/rtrp/repos/light-meter/light_meter.py +``` diff --git a/light-wave/attachments/screenshot.png b/light-wave/attachments/screenshot.png new file mode 100644 index 0000000..7cfaf85 Binary files /dev/null and b/light-wave/attachments/screenshot.png differ diff --git a/light-wave/light-wave.md b/light-wave/light-wave.md new file mode 100644 index 0000000..9c85a08 --- /dev/null +++ b/light-wave/light-wave.md @@ -0,0 +1,66 @@ +# Return to Ritherdon: Light Wave + +This is a support project to help test and monitor the Light Meter in +the factory (Ritherdon). It provide about a minutes worth of streamed +light readings from the facory and displays both readings as animated +line graph. When the exhibition is live, the intention is for it to +provide additional information in the gallery space (I.E. Castlefield +Gallery) for the viewers. + +For more information about the 'Return to Ritherdon' project, please +you the links below: + +- [Light Meter Code](https://git.abbether.net/return-to-ritherdon/light-meter) +- [Light Meter Documentation](https://git.abbether.net/return-to-ritherdon/rtr-docs/src/branch/master/light-meter) +- [Relay Code](https://git.abbether.net/return-to-ritherdon/relay) +- [Relay Documentation](https://git.abbether.net/return-to-ritherdon/rtr-docs/src/branch/master/relay) +- [Midpoint Code](https://git.abbether.net/return-to-ritherdon/midpoint) +- [Midpoint + Documentation](https://git.abbether.net/return-to-ritherdon/rtr-docs/src/branch/master/midpoint) + +They will provide a much broader overview of how the various parts and +projects fit together. Because Light Wave is a support project, there +is no distinct connection between this project and the three main ones +(I.E. Light Meter, Relay and Midpoint). + +![Screenshot](attachments/screenshot.png) + +This program is set-up as a glorified script (all in one file). So, +there is not much to document. Essentially, all the main code resides +in `light-wave.py` which you can read by clicking the link below: + +- [light-wave.ph](https://git.abbether.net/return-to-ritherdon/light-wave/src/branch/master/light-wave.py) + +## Project Set-up + +This assumes you are on a Linux (Debian/Ubuntu based) machine. Because +of project constraints, other environments have not been tested. + +```bash +# Clone repo. if you haven't already. +git clone http://git.abbether.net/return-to-ritherdon/light-wave.git +cd light-wave + +# Create and activate the virtual environment +python3 -m venv venv +source venv/bin/activate + +# Install dependencies (with pip) +pip install -r requirements.txt + +# Run the program +python light-wave.py +``` + +**You might need to add additional packages (via `apt`)**. The most +notable reason why is because Matplotlib needs some extra things to +run. It looks like the list depends on what you've already installed +on your system -- I've only checked Debian. Use the following link for +more information about installing stuff more Matplotlib: + +- [Matplotlib Install Notes](https://matplotlib.org/stable/users/installing.html) + +There is not much more to say on this one. It is basically a script +gluing the various parts of Matplotlib together. If you would like to +extend this program, you will need to use the Matplotlib link above +and learn more about how that works. diff --git a/midpoint/attachments/main-proj-architecture.dot b/midpoint/attachments/main-proj-architecture.dot new file mode 100644 index 0000000..5518528 --- /dev/null +++ b/midpoint/attachments/main-proj-architecture.dot @@ -0,0 +1,19 @@ +digraph overview { + node [fontname = Arial]; + l1 -> server; + l2 -> server; + server -> r1; + server -> r2; + r1 -> server; + r2 -> server; + l1 [label = "Light Meter 1", color = lightblue, style = filled]; + l2 [label = "Light Meter 2", color = orange, style = filled]; + r1 [label = "Relay 1", color = lightblue, style = filled]; + r2 [label = "Relay 2", color = orange, style = filled ]; + subgraph cluster0 { + style = filled; + color = lightgrey; + server; + } + server [label = "Midpoint (Server)", style = filled, color = white]; +} diff --git a/midpoint/attachments/main-proj-architecture.png b/midpoint/attachments/main-proj-architecture.png new file mode 100644 index 0000000..d8366e4 Binary files /dev/null and b/midpoint/attachments/main-proj-architecture.png differ diff --git a/midpoint/attachments/swagger-ui.png b/midpoint/attachments/swagger-ui.png new file mode 100644 index 0000000..4b679b2 Binary files /dev/null and b/midpoint/attachments/swagger-ui.png differ diff --git a/midpoint/rtr-midpoint.md b/midpoint/rtr-midpoint.md index e69de29..0ef19b0 100644 --- a/midpoint/rtr-midpoint.md +++ b/midpoint/rtr-midpoint.md @@ -0,0 +1,331 @@ +# Return to Ritherdon: Midpoint + +Midpoint is one of three smaller projects which make-up 'Personal +Flash in Real-Time' -- which is one artwork within the main 'Return to +Ritherdon' project. You should view the three smaller projects as one +project. And, for the purpose of this documentation, I will refer to +'Personal Flash in Real-Time' as a system instead of an artwork. + +For more information on the 'Return to Ritherdon' project, use the +following link: + +- [Return to Ritherdon Overview](https://git.abbether.net/return-to-ritherdon/rtr-docs) + +## 'Personal Flash in Real-Time': Project Overview + +The overall system ('Personal Flash in Real-Time') consists of three +separate/smaller projects. You should not view them as individual +pieces within the overall project. From an artwork point-of-view, +'Personal Flash in Real-Time' is one piece. The name of the software +projects are 'Light Meter' (which is this one), 'Midpoint' and +'Relay'. All three projects reside in their own git repositories. You +can find the repositories at the following links: + +- [Light Meter](https://git.abbether.net/return-to-ritherdon/light-meter) +- [Mid-Point](https://git.abbether.net/return-to-ritherdon/midpoint) +- [Relay](https://git.abbether.net/return-to-ritherdon/relay) + +The (technical) aim of the project is to turn a set of lights on at +the gallery when the welding machines are active in the welding booths +at Ritherdon. The solution we arrived at was a three-stage +process. The stages are as follows: + +1. Monitor the light levels in the welding booths at Ritherdon and + send that information to a sever (Light Meter). +2. Receive the light readings and store them in a database and make + them available for others to access (Midpoint). +3. Have the lights installed at the gallery connected to wi-fi enabled + relays which request the latest light readings from the server. If + the readings are above a certain threshold, have the light in the + gallery turn on (otherwise, turn off). The relays are responsible + for turning the lights on and off (Relay). + +Each step should require no human intervention. + +For more information on how each project accomplishes its task, please +use the (repo.) links above. Otherwise, here is an diagram to help +explain the three stages mentioned above. + +![Main Project Architecture](attachments/main-proj-architecture.png) + +## Hardware Specifications + +There are no specific hardware requirements. If you can get an machine +to run a server (E.G. Nginx or Apache), you should be good to +go. Unfortunately, the scope of the project meant the amount of +support for hardware and software is limited to an x86 Linux based +machine running Nginx. I decided to run a virtual machine on Amazon +Web Services. + +- [Amazon Web Services](https://aws.amazon.com/) (A.W.S.) + +## Software Requirements + +I have set-up the server to run on Linux (I.E. Ubuntu) with an Nginx +server -- on an x86 machine. Any other variation on that +(I.E. Windows), you will be on your own. The reason why is because I +have not tested it. How you acquire the hardware is up to you. For the +intents of the project, I used a virtual machine on Amazon Web +Services. Links for various parts of the set-up are below: + +- [https://ubuntu.com/](https://ubuntu.com/) +- [Nginx](https://www.nginx.com/) +- [Python Flask](https://flask.palletsprojects.com/en/2.0.x/) +- [Gunicorn](https://gunicorn.org/) +- [Supervisor](https://pypi.org/project/supervisor/) (Python) +- [SQLite Database](https://sqlite.org/index.html) +- [SQL Alchemy](https://www.sqlalchemy.org/) (O.R.M.) +- [Swagger REST API](https://swagger.io/) + +## Software Set-up + +Below is an overview of the files and directory structure. + +```shell +app/ +├── api.py <-------- REST API entry point. +├── app.py <------- 'Main' program entry point. +├── build_database.py <-- Builds database (use first). +├── config.py <----- Program config's for Flask and Swagger. +├── models <-------- Objects which database rows are mapped to. +├── __pycache__ +├── readings.db <--- The SQLite database. +├── services <------ 'Business logic' for api.py entry points. +├── static <------- Images/Favicons/Style Sheets. +├── swagger.yml <--- YAML config. file for Swagger (REST API). +└── templates <----- HTML views. +``` + +### The Program (Python and Virtual Environment) + +**I have omitted instructions on creating user accounts beyond the +defaults** because that comes with a fair bit of context specific +information which is beyond the scope of this documentation. On top of +that, the project's budget did not allow for extended research on +various Cloud Platforms and server architecture, in-general. + +After you have established a V.M. on A.W.S. or your own server, you +will need to clone the repository (**I am assuming this is via SSH**). + +```bash +# Adjust the directories to how you prefer it. These are just my defaults. +mkdir www +cd www +git clone http://git.abbether.net/return-to-ritherdon/midpoint.git +cd midpoint +``` + +From there, you can create a Python virtual environment if you prefer +to keep things isolated. You can ignore the virtual environment step +and install the requirements at a system-wide level. If you do that, +you will need to use `pip3` instead of `pip`. + +```bash +# Adjust the path to suit to environment. +python3 -m venv ~/repos/midpoint/venv + +# Install the requirements... +(use pip3 if you're not using a virtual environment) +pip install -r requirements.txt +``` + +As an aside, I created a virtual environment with `python3 -m venv +~/www/midpoint/my-env` whilst in development. This environment might +still be around the production server, used during the +exhibition. **If you are completing a fresh install, this is not +relevant to you. Please ignore.** + + +### The Server + +The host name for the server used during the exhibition was +`piapi`. So, I will use that in the documentation below. **Please make +sure you replace `piapi` with the host name you are using.** + +I used Nginx and Gunicorn for the exhibition so that is all this +documentation will focus on. Midpoint should work on other servers +(like Apache) but I have not tested it. + +The Nginx configuration file is located at: + +- `/etc/nginx/sites-enabled/piapi` + +You can access the file with `sudo nano +/etc/nginx/sites-enabled/piapi` when logged into the server. + +Because Nginx is responsible for the static side of the website, +Gunicorn is needed to operate the Python side of it. Nginx knows +how/when to pass control over to Gunicorn because it is configured in +the … sites-enables/piapi configuration file (mentioned above). With +that said, Gunicorn still needs to be set-up for everything to run +properly. It is worth pointing out, the "static" part of the site will +still run when Gunicorn is not running but that is a practically +useless feature. To run Gunicorn, enter the following command into the +terminal (of logged in V.M), + +```bash +# You can adjust the '-w 3' if you have a more powerful server. Also, +the 'connext_app' related to the use of the Swagger API code. +gunicorn -w 3 server:connex_app +``` + +The `-w 3` bit refers to the total number of workers (processors) +Gunicorn will use whilst running. The general rule to work that out it +/(number of processors * 2) + 1. At the time of writing, the virtual +machine used for the exhibition is a very basic one-core machine so +that is why three workers is used. + +One problem with Gunicorn is it blocks the terminal when using it in +its default way. To get around this, I have install Supervisor to +manage it. Supervisor handles the auto-restart after a crash and +background-task management of it too. To install it, run the following +command, + +```bash +sudo apt install supervisor +``` + +When Supervisor is installed, you need to create a config. file. The +file for this project is stored at, + +- `/etc/supervisor/conf.d/spiapi.conf` + +The log files (specified in the .conf) file are, + +- `/var/log/midpoint/midpoint.err.log` +- `/var/log/midpoint/midpoint.out.log` + +You will need to recreate the directory they are stored in if you are +installing this site on a new system. The easiest way to do that is to +run the following command, + +```bash +sudo mkdir -p /var/log/midpoint +sudo touch /var/log/midpoint/midpoint.err.log +sudo touch /var/log/midpoint/midpoint.out.log +``` + +When you have finished making these changes, you will need to restart +Supervisor. To do that, run the following command, + +```bash +sudo supervisor reload +``` + +It might take a little while for the service to restart so if you +still see "Bad Gateway" messages in the browser, that might be why. + +You might find Gunicorn is not installed in the virtual-environment +(if you have decided to not install one or you simply forget to +activate like I have a habit of doing), it that is the case, you +should find it at, + +- `home/ubuntu/.local/bin/gunicorn` + +This might, also, mean you need to use `apt` and not `pip3`. + +The config. file for Supervisor should look something like the +following, (remember to adjust the places where `ubuntu` is with your +servers account name -- if it differs from `ubuntu`) + +```bash +[program:midpoint] +directory=/home/ubuntu/www/midpoint/app +command=/home/ubuntu/.local/bin/gunicorn -w 3 server:connex_app +user=ubuntu +autostart=true +autorestart=true +stopasgroup=true +killasgroup=true +stderr_logfile=/var/log/midpoint/midpoint.err.log +stdout_logfile=/var/log/midpoint/midpoint.out.log +``` + +The config. file for Nginx should look like the following, + +```bash +server { + listen 80; + server_name 35.176.235.94; + + location /static { + alias /home/ubuntu/www/midpoint/app/static; + } + + location / { proxy_pass http://localhost:8000; include + /etc/nginx/proxy_params; proxy_redirect off; } } +``` + +**I did not set-up the server to use HTTPS because it was outside the +scope of the project.** Again, replace `ubuntu` with your servers +username. + +### Flask & Swagger + +To access the A.P.I. user-interface (via Swagger), enter + +-`http://0.0.0.0:5000/api/ui/` + +- [Real Python](https://realpython.com/flask-connexion-rest-api/#using-connexion-to-add-a-rest-api-endpoint) + +Real Python provides a good walk-through for setting-up a website using +the Flask framework. Real Python, also, provides guides on creating +websites with Python and its various website frameworks. + +I have imported the `connexion` project into this one. By doing this, +I can use Swagger and its U.I. When you have the server running, go to +`localhost:5000/api/swagger`. When there, you can test the A.P.I. out +by sending it "gets" and "posts". + +![Swagger Screenshot](attachments/swagger-ui.png) + +The Swagger endpoint are configured in a YAML file at, + +- [midpoint/app/swagger.yml](https://git.abbether.net/return-to-ritherdon/midpoint/src/branch/unstable/app/swagger.yml) + +### Database and O.R.M. + +The project uses a SQLite database to store light reading and any +device status updates. To write to the database, I used SQL Alchemy as +a Object Relational Mapper (O.R.M). The database is called, + +- `readings.db` + +Before you can start the program, you will need to build the +database. To do that, you will need to run the following commands, + +```bash +# Make sure you are in the 'app' directory. Adjust the 'cd' path to +# match your set-up. +cd ~/www/midpoint/app/ + +# If you have created and activated a virtual environment, you can +# enter 'python' instead of 'python3'. +python3 build-database.py +``` + +This will clear the database if one is already set-up and then build a +new one. + +## Notes on System Limitations + +### 1. Connection Times-Out on Large JSON Packets + +The biggest thing to remember the REST API calls which grab 'all' the +light readings from every device, will start to fail fairly quickly +after a 'clean install'. The reason why is because the JSON package +becomes too large and the connection times out. You might get better +results on a more powerfully spec'd server than the one used for the +exhibition but I have not tested this so I cannot confirm this. + +### 2. Three Light-Meters and Relays Specified but Only Two (of each) Used + +Ritherdon (the factory) has three welding booths so 'Personal Flash in +Real-Time' was designed with this in mind. Over the course of the +development process, the use of the third booth was not +needed/wanted. By that time, the code, database and models had already +been created. I decided to opt for the lazy option and keep the +references to the third booth instead of removing it because it was +not impeding on the system in any way. I was, also, cautious about the +chance of a change happening late into the development cycle were I +would need to put it back it. diff --git a/relay/attachments/5v-relay-normally-closed-layout.png b/relay/attachments/5v-relay-normally-closed-layout.png new file mode 100644 index 0000000..f652e4b Binary files /dev/null and b/relay/attachments/5v-relay-normally-closed-layout.png differ diff --git a/relay/attachments/5v-relay-normally-open-layout.png b/relay/attachments/5v-relay-normally-open-layout.png new file mode 100644 index 0000000..2145478 Binary files /dev/null and b/relay/attachments/5v-relay-normally-open-layout.png differ diff --git a/relay/attachments/5v-relay-pins-layout.png b/relay/attachments/5v-relay-pins-layout.png new file mode 100644 index 0000000..10921cd Binary files /dev/null and b/relay/attachments/5v-relay-pins-layout.png differ diff --git a/relay/attachments/main-proj-architecture.dot b/relay/attachments/main-proj-architecture.dot new file mode 100644 index 0000000..438574d --- /dev/null +++ b/relay/attachments/main-proj-architecture.dot @@ -0,0 +1,20 @@ +digraph overview { + node [fontname = Arial]; + l1 -> server; + l2 -> server; + server -> r1; + server -> r2; + r1 -> server; + r2 -> server; + l1 [label = "Light Meter 1", color = lightblue, style = filled]; + l2 [label = "Light Meter 2", color = orange, style = filled]; + r1 [label = "Relay 1", color = lightblue, style = filled]; + r2 [label = "Relay 2", color = orange, style = filled ]; + server [label = "Midpoint (Server)"]; + subgraph cluster0 { + style = filled; + color = lightgrey; + r1; + r2; + } +} diff --git a/relay/attachments/main-proj-architecture.png b/relay/attachments/main-proj-architecture.png new file mode 100644 index 0000000..7b125dd Binary files /dev/null and b/relay/attachments/main-proj-architecture.png differ diff --git a/relay/attachments/pinout-terminal.png b/relay/attachments/pinout-terminal.png new file mode 100644 index 0000000..c7f9533 Binary files /dev/null and b/relay/attachments/pinout-terminal.png differ diff --git a/relay/attachments/wiring-diagram-relay.png b/relay/attachments/wiring-diagram-relay.png new file mode 100644 index 0000000..15aab48 Binary files /dev/null and b/relay/attachments/wiring-diagram-relay.png differ diff --git a/relay/rtr-relay.md b/relay/rtr-relay.md index e69de29..678b59a 100644 --- a/relay/rtr-relay.md +++ b/relay/rtr-relay.md @@ -0,0 +1,287 @@ +# Return to Ritherdon: Relay + +Relay is one of three smaller projects which make-up the 'Personal +Flash in Real-Time' -- which is one artwork with the main 'Return to +Ritherdon' project.You should view the three smaller projects as one +project. And, for the purpose of this documentation, I will refer to +'Personal Flash in Real-Time' as a system instead of an artwork. + +For more information on the 'Return to Ritherdon' project, use the +following link: + +- [Return to Ritherdon Overview](https://git.abbether.net/return-to-ritherdon/rtr-docs) + +### 'Personal Flash in Real-Time': Project Overview + +The overall system ('Personal Flash in Real-Time') consists of three +separate/smaller projects. You should not view them as individual +pieces within the overall project. From an artwork point-of-view, +'Personal Flash in Real-Time' is one piece. The name of the software +projects are 'Light Meter' (which is this one), 'Midpoint' and +'Relay'. All three projects reside in their own git repositories. You +can find the repositories at the following links: + +- [Light Meter](https://git.abbether.net/return-to-ritherdon/light-meter) +- [Mid-Point](https://git.abbether.net/return-to-ritherdon/midpoint) +- [Relay](https://git.abbether.net/return-to-ritherdon/relay) + +The (technical) aim of the project is to turn a set of lights on at +the gallery when the welding machines are active in the welding booths +at Ritherdon. The solution we arrived at was a three-stage +process. The stages are as follows: + +1. Monitor the light levels in the welding booths at Ritherdon and + send that information to a sever (Light Meter). +2. Receive the light readings and store them in a database and make + them available for others to access (Midpoint). +3. Have the lights installed at the gallery connected to wi-fi enabled + relays which request the latest light readings from the server. If + the readings are above a certain threshold, have the light in the + gallery turn on (otherwise, turn off). The relays are responsible + for turning the lights on and off (Relay). + +Each step should require no human intervention. + +For more information on how each project accomplishes its task, please +use the (repo.) links above. Otherwise, here is an diagram to help +explain the three stages mentioned above. + +![Main Project Architecture](attachments/main-proj-architecture.png) + +## Hardware Specifications + +Here are a list of parts used in this project: + +- [Raspbian](https://www.raspberrypi.org/downloads/raspbian/) (You can + use the G.U.I. or "headless" version) +- [Raspberry Pi + 4](https://www.raspberrypi.org/products/raspberry-pi-4-model-b/) (I + am assuming you have the appropriate power cable, S.D. cards Etc.) +- [Single Channel 5v Relay](https://www.amazon.co.uk/Dealikee-Module-Indicator-Channel-Arduino/dp/B08ZJ9T355/ref=sr_1_12?dchild=1&keywords=5v+relay+module&linkCode=gs3&qid=1635877670&qsid=262-0370227-8667213&sr=8-12&sres=B08YK9V3V6%2CB07RKH9KLM%2CB06XK6HCQC%2CB01H2D2RI0%2CB08MTD5BPJ%2CB07PZC9ZMM%2CB07CNR7K9B%2CB08ZJ9T355%2CB07V1YQQGL%2CB07MY2R2ML%2CB07G71S7VP%2CB09C2ZHXXP%2CB08GPF9FNX%2CB09CN81J32%2CB07SDLJSWB%2CB08YJ6TS29%2CB08V15SNZS%2CB09DS3DD1J%2CB08KWPMP2V%2CB07TTVYGC8&srpt=RELAY) + +## Points of Interest for Understanding How Relays work + +I have included this section if you are unfamiliar with what a relay +is, how it works and how it connects/works with a Raspberry Pi. If you +are already familiar with relays, you can skip this section. + +### Checking Your Raspberry Pi's Hardware Layout + +Because there are multiple versions of the Raspberry Pi, the layout of +the General Purpose Input/Output (G.P.I.O.) Pins differ. A quick way +to find out how the G.P.I.O. pins are laid out, for the Pi you are +currently working on, is to open a terminal and entering the following +command `pinout`. + +Doing this will lead to you seeing something similar to the image +below, + +![pinout-terminal](attachments/pinout-terminal.png) + +More information about this can be found at the following URL: + +- [Checking Raspberry Pi Board Version](https://www.raspberrypi-spy.co.uk/2012/09/checking-your-raspberry-pi-board-version/][Raspberry Pi Board Information) + +### Wiring-Up the Relay + +- [Wiring Single Channel Relay with Raspberry Pi](https://www.14core.com/wiring-single-channel-relay-with-raspberry-pi-on-wiringpi-python/) + +I used this article/blog post (linked above) as a starting-point for +the relay part of the project. It includes software written in C and +Python but I have stuck to just Python for this project. You can see +how the relay is wired-up to the Pi in the image below. + +![Wiring Diagram Relay](attachments/wiring-diagram-relay.png) + +### General Overview of Controlling Relays + +- [Four Ways to Control Electronic Relays](https://makezine.com/2018/03/19/control-electronic-relays/) + +This is a primer for understanding how to control relays and the +various types of relays at your disposal. The list is not exhaustive +but is enough to get you going. + +- [YouTube Guide](https://www.youtube.com/watch?v=58XWVDnB7Ss) + +I find the guy in this video difficult to understand but he gets his +message across well enough. He explains how a relay works and how to +connect it to an *Arduino Board* and control a light bulb. If you are +not familiar with how relays work, this video should give you a good +grounding in it. /Note: This video does not use a Raspberry Pi so the +information is limited to just the relay and the light part of the +project. + +- [How to Set-up a 5v Relay](https://www.circuitbasics.com/setting-up-a-5v-relay-on-the-arduino/) + +The link above focuses on using an *Arduino Board* but you can +determine what pin does what. The example in the link, also, +includes a thermistor in its set-up which does not apply to this +project. The image below is taken from the site and +highlights what each pin is. + +![Relay Pins Layout](attachments/5v-relay-pins-layout.png) + +- **NO (Normally Open)**: In the normally open configuration, when the + relay receives a HIGH signal the 120-240V switch closes and allows + current to flow from the C terminal to the NO terminal. A LOW signal + deactivates the relay and stops the current. So if you want the HIGH + signal to turn ON the relay, use the normally open terminal. See + images below for further information. +- **NC (Normally Closed)**: In the normally closed configuration, a + HIGH signal opens the switch and interrupts the 120-240V current. A + LOW signal closes the switch and allows current to flow from the C + terminal to the NC terminal. Therefore, if you want the HIGH signal + to turn OFF the 120-240V current, use the normally closed + terminal. See images below for further information. + +![Relay Normally Open Layout](attachments/5v-relay-normally-open-layout.png) + +![Relay Normally Closed Layout](attachments/5v-relay-normally-closed-layout.png) + +## Project Set-up + +Relay consists of two parts: hardware and software. The hardware part +focuses on the electronics attached to the Raspberry Pi 4 and the +software side focuses on installing software dependencies onto the +operating system and 'maintenance' tasks for sustained use of the +device (whilst in operation). For the code written specifically for +this project, please use the following link: + +- [Relay Software Repository](https://git.abbether.net/return-to-ritherdon/relay) + +### Initial Raspbian Set-up + +Upon the initial installation of Raspbian on to the Pi, you need to make sure the following is established: + +- The username is `rtrp`. +- The host-name is `gallery#` (where "#" is either 1 and 2). +- The Pi is set to auto-login with the `rtrp` account. + +You can set the Pi up to automatically login to the desktop but the +recommended option is to login to a "headless" environment +(I.E. console-mode). Remember, you can only log into the desktop +environment if your version of Raspbian has one. The final version of +this project does not expect one. + +### Hardware Preparations + +### Network Connections + +Before installing Raspberry Pi in its final location +(gallery/exhibition), make sure it can connect to the galleries +internet - either via Wi-Fi or Ethernet cable. If you use an Ethernet +cable, you do not need to do anything, but Wi-Fi requires a little +work on the command-line (if you are using a 'headless' version of +Raspbian). If you are unsure how to connect to a router via Wi-Fi, use +the following link to learn how: + +- [Raspbian Wi-Fi Tutorial](https://www.raspberrypi.org/documentation/configuration/wireless/wireless-cli.md) + +### Relay Set-up + +To connect the relay to the Raspberry Pi, refer to the following image: + +- [the image above](https://git.abbether.net/return-to-ritherdon/rtr-docs/src/branch/unstable/relay/rtr-relay.md#wiring-up-the-relay) + +### Software Preparations + +Depending on what version of Linux/Raspbian you are running, you might +need to install some dependencies. I have listed the common ones I +came across whilst developing this project. But, you might need to +rely on your own cunning to track down missing dependencies. + +```bash +# Don't forget to apt update and upgrade first... +sudo apt install python3-pip + +sudo pip3 install requests +sudo pip3 install RPi.GPIO + +# You might need to install RPi.GPIO via apt +sudo apt install python3-rpi.gpio + +# I will explain why this is here below... +mkdir ~/repos +``` + +**Note: I decided not to create/use a (Python) virtual environment +because of the projects objectives. I expect the software in this +repository to run on an unmanned machine with only one task to +complete. The environment this project will run in/on will not change +throughout the course of the exhibition. So, the redundancies afforded +by the virtual environment are not needed.** + +When you clone this repository, you need to make sure you clone it +into the following location: `/home/rtrp/repos/relay/`. From +there, run the following command, + +```bash +# This must be the first thing you run after you have cloned +# the repository. +. ~/repos/relay/make-log-files.sh +``` + +You can test the code is working properly by running it. You can do +that by entering `sudo python3 ~/repos/relay/reply.py`. This is +assuming the server specified in `reply.py` is set-up and working as +intended. The server is developed in the 'Midpoint' project +repository. Links for 'Midpoint' are as follows: + +- [Midpoint Code](https://git.abbether.net/return-to-ritherdon/relay/src/branch/master) +- [Midpoint Documentation](https://git.abbether.net/return-to-ritherdon/rtr-docs/src/branch/master/midpoint) + +Note: For some reason, I had trouble running `relay.py` without +sudo. I would sometimes get an error message saying "RPi.GPIO is not +available/installed" (paraphrased). If you manage to get it working +without the use of sudo, remain as you were. Otherwise, keep a mental +note of this if you come across the problem. + +### Set-Up Program as a Cronjob + +When you are ready to run this project as intended, you can set-up a +cron-job for it. To do so enter `sudo crontab -e` into the console (see +note about sudo above). You might need to select an editor if this is +your first time setting up a cron-job. I tend to go for Nano -- which +is option "1" most of the time. When the crontab file opens, enter the +following commands at the bottom of the file, + +```bash +@reboot bash /home/rtrp/repos/relay/startup.sh & +00 18 * * * /home/rtrp/repos/relay/shutdown.sh +``` + +These tasks make the Raspberry Pi send a message to the sever to +indicate its/their status ("on" or "off") and makes the `startup.sh` +script run. At this point, you should be able to walk away and let the +Pi do its thing. This is assuming the server is up and running and the +Pi is connected to the world-wide-web. If all is successful, you will +notice the Pi will turn itself off at 18:00 (6 p.m.) and will start +receiving reading when you turn it on without any input from +you. Unfortunately, the Pi can only manage the shutdown procedure on +its own. You will need to turn it on. (This has been accounted whilst +the exhibition is open.) + +This next part is optional. To make sure the Pi sends a "powering +down" message to the server, I tend you create an alias called +`powerdown`. When you type this into the console, it runs the +`shutdown.sh` script -- which has the shutdown command within it. To +make the alias permanent, enter `alias='~/repos/relay/shutdown.sh` +into `~/.bashrc`. This is easier to test the bespoke shutdown +procedure is working as intended. You can, also, adjust the time in +the crontab or run the script by running the script like you normally +would but I find them to be frustrating to do in this instance. + +### Running the Program Manually (Quick Reference) + +If you have already completed the other installation/set-up tasks, use +the code below. + +```bash +# This assumes you have cloned the repository and completed the other +# installation tasks. +sudo python3 ~/repos/relay/reply.py +``` + +(Note: This is here so I have something to quickly refer to after I've +forgot how the Relay works -- because I've not used it for a long +time.)