Browse Source

Squashed commit of the following:

commit e23be46f54
Author: Craig Oates <craig@craigoates.net>
Date:   Fri Nov 5 16:59:01 2021 +0000

    update Midpoint doc.

commit 70e23d0902
Author: Craig Oates <craig@craigoates.net>
Date:   Fri Nov 5 16:55:27 2021 +0000

    update Midpoint doc.

commit 3daa38662a
Author: Craig Oates <craig@craigoates.net>
Date:   Fri Nov 5 16:46:04 2021 +0000

    update README doc.

commit 2e9d1df94d
Author: Craig Oates <craig@craigoates.net>
Date:   Fri Nov 5 16:19:39 2021 +0000

    create and populate Light Wave doc.

commit 73464777fe
Author: Craig Oates <craig@craigoates.net>
Date:   Thu Nov 4 20:34:37 2021 +0000

    add Return to Ritherdon Project Overview .dot file.

    This is the file used to generate the .png  version of the file in the
    main README.md file.

commit 76710d26cb
Author: Craig Oates <craig@craigoates.net>
Date:   Thu Nov 4 20:32:30 2021 +0000

    update README doc. diagrams.

    I added a .dot file for the Return to Riterdon project overview and
    fix the image links for so the diagrams sit in their correct places
    within the document.

commit 131bdefdc3
Author: Craig Oates <craig@craigoates.net>
Date:   Thu Nov 4 20:27:49 2021 +0000

    add .dot file for diagram in README.

    This is the file used to illustrate the how 'Personal Flash in
    Real-Time' fits into the 'Return to Ritherdon' project.

commit 6dae2040dc
Author: Craig Oates <craig@craigoates.net>
Date:   Thu Nov 4 20:27:27 2021 +0000

    update README doc (main project overview).

commit d20d592495
Author: Craig Oates <craig@craigoates.net>
Date:   Thu Nov 4 19:39:12 2021 +0000

    update Midpoint doc.

commit db74ec5d06
Author: Craig Oates <craig@craigoates.net>
Date:   Thu Nov 4 19:14:05 2021 +0000

    populate midpoint doc.

commit a4ecffeec9
Author: Craig Oates <craig@craigoates.net>
Date:   Wed Nov 3 20:31:37 2021 +0000

    start populating Midpoint doc.

    This is a work in progress (end of session) commit.

commit bf8a961f99
Author: Craig Oates <craig@craigoates.net>
Date:   Wed Nov 3 20:02:07 2021 +0000

    fix typo in Relay doc.

commit 8902037b83
Author: Craig Oates <craig@craigoates.net>
Date:   Wed Nov 3 19:53:14 2021 +0000

    update Relay doc.

commit 0e62c64f06
Author: Craig Oates <craig@craigoates.net>
Date:   Tue Nov 2 19:00:20 2021 +0000

    stub out further sections for Relay doc.

    This is prep. work for expanding the documentation for the Relay
    project. End of session commit, though, which is the reason why the
    sections are not filled out.

commit af03002f48
Author: Craig Oates <craig@craigoates.net>
Date:   Tue Nov 2 18:50:31 2021 +0000

    populated Relay doc.

    This is a rough transfer of my personal notes in to the public doc's
    for the Relay project. I've not gone through it properly so expect
    mistakes and it needing a good proof-read.

commit c8eba160fb
Author: Craig Oates <craig@craigoates.net>
Date:   Tue Nov 2 18:07:02 2021 +0000

    update Light Meter doc.

commit 755db34e92
Author: Craig Oates <craig@craigoates.net>
Date:   Tue Nov 2 17:52:21 2021 +0000

    update light-meter doc.

commit d28dea87c4
Author: Craig Oates <craig@craigoates.net>
Date:   Tue Nov 2 17:15:13 2021 +0000

    add install section to Eyes and Ears doc.

commit d5e6440297
Author: Craig Oates <craig@craigoates.net>
Date:   Tue Nov 2 17:09:27 2021 +0000

    add links to other projects (Eyes and Ears doc's).

commit 5b2583c00b
Author: Craig Oates <craig@craigoates.net>
Date:   Tue Nov 2 16:59:32 2021 +0000

    populate the Eyes and Ears section.

commit b3408532d8
Author: Craig Oates <craig@craigoates.net>
Date:   Tue Nov 2 12:57:48 2021 +0000

    change Ross to Andy.

    At some point, I forgot when it was, Ross was replaced by Andy as a
    welder. This name change is just me dotting the i's and crossing the
    t's.
master
Craig Oates 3 months ago
parent
commit
109798a205
31 changed files with 1065 additions and 114 deletions
  1. +32
    -35
      README.md
  2. +14
    -0
      attachments/main-proj-architecture.dot
  3. BIN
      attachments/main-proj-architecture.png
  4. +29
    -0
      attachments/return-to-ritherdon-project-overview.dot
  5. BIN
      attachments/return-to-ritherdon-project-overview.png
  6. +17
    -0
      eyes-and-ears/attachments/app-internals.dot
  7. BIN
      eyes-and-ears/attachments/app-internals.png
  8. BIN
      eyes-and-ears/attachments/eyes-and-ears-screenshot-1.png
  9. BIN
      eyes-and-ears/attachments/eyes-and-ears-screenshot-2.png
  10. BIN
      eyes-and-ears/attachments/gui-breakdown.png
  11. +21
    -0
      eyes-and-ears/attachments/system-overview.dot
  12. BIN
      eyes-and-ears/attachments/system-overview.png
  13. +154
    -0
      eyes-and-ears/rtr-eyes-and-ears.md
  14. +5
    -5
      health-and-safety/photosensitive_epilepsy.md
  15. +20
    -0
      light-meter/attachments/main-proj-architecture.dot
  16. BIN
      light-meter/attachments/main-proj-architecture.png
  17. +50
    -74
      light-meter/rtr-light-meter.md
  18. BIN
      light-wave/attachments/screenshot.png
  19. +66
    -0
      light-wave/light-wave.md
  20. +19
    -0
      midpoint/attachments/main-proj-architecture.dot
  21. BIN
      midpoint/attachments/main-proj-architecture.png
  22. BIN
      midpoint/attachments/swagger-ui.png
  23. +331
    -0
      midpoint/rtr-midpoint.md
  24. BIN
      relay/attachments/5v-relay-normally-closed-layout.png
  25. BIN
      relay/attachments/5v-relay-normally-open-layout.png
  26. BIN
      relay/attachments/5v-relay-pins-layout.png
  27. +20
    -0
      relay/attachments/main-proj-architecture.dot
  28. BIN
      relay/attachments/main-proj-architecture.png
  29. BIN
      relay/attachments/pinout-terminal.png
  30. BIN
      relay/attachments/wiring-diagram-relay.png
  31. +287
    -0
      relay/rtr-relay.md

+ 32
- 35
README.md View File

@ -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).

+ 14
- 0
attachments/main-proj-architecture.dot View File

@ -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)"];
}

BIN
attachments/main-proj-architecture.png View File

Before After
Width: 950  |  Height: 646  |  Size: 190 KiB Width: 368  |  Height: 251  |  Size: 25 KiB

+ 29
- 0
attachments/return-to-ritherdon-project-overview.dot View File

@ -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"];
}
}

BIN
attachments/return-to-ritherdon-project-overview.png View File

Before After
Width: 950  |  Height: 254  |  Size: 79 KiB Width: 1097  |  Height: 176  |  Size: 26 KiB

+ 17
- 0
eyes-and-ears/attachments/app-internals.dot View File

@ -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"];
}

BIN
eyes-and-ears/attachments/app-internals.png View File

Before After
Width: 502  |  Height: 387  |  Size: 45 KiB

BIN
eyes-and-ears/attachments/eyes-and-ears-screenshot-1.png View File

Before After
Width: 1202  |  Height: 934  |  Size: 719 KiB

BIN
eyes-and-ears/attachments/eyes-and-ears-screenshot-2.png View File

Before After
Width: 1202  |  Height: 934  |  Size: 687 KiB

BIN
eyes-and-ears/attachments/gui-breakdown.png View File

Before After
Width: 3821  |  Height: 2955  |  Size: 3.9 MiB

+ 21
- 0
eyes-and-ears/attachments/system-overview.dot View File

@ -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;];
}

BIN
eyes-and-ears/attachments/system-overview.png View File

Before After
Width: 590  |  Height: 333  |  Size: 29 KiB

+ 154
- 0
eyes-and-ears/rtr-eyes-and-ears.md View File

@ -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.

+ 5
- 5
health-and-safety/photosensitive_epilepsy.md View File

@ -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


+ 20
- 0
light-meter/attachments/main-proj-architecture.dot View File

@ -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)"];
}

BIN
light-meter/attachments/main-proj-architecture.png View File

Before After
Width: 950  |  Height: 646  |  Size: 190 KiB Width: 409  |  Height: 272  |  Size: 23 KiB

+ 50
- 74
light-meter/rtr-light-meter.md View File

@ -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
```

BIN
light-wave/attachments/screenshot.png View File

Before After
Width: 762  |  Height: 683  |  Size: 54 KiB

+ 66
- 0
light-wave/light-wave.md View File

@ -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.

+ 19
- 0
midpoint/attachments/main-proj-architecture.dot View File

@ -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];
}

BIN
midpoint/attachments/main-proj-architecture.png View File

Before After
Width: 368  |  Height: 251  |  Size: 24 KiB

BIN
midpoint/attachments/swagger-ui.png View File

Before After
Width: 990  |  Height: 740  |  Size: 56 KiB

+ 331
- 0
midpoint/rtr-midpoint.md View File

@ -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.

BIN
relay/attachments/5v-relay-normally-closed-layout.png View File

Before After
Width: 1280  |  Height: 475  |  Size: 100 KiB

BIN
relay/attachments/5v-relay-normally-open-layout.png View File

Before After
Width: 1280  |  Height: 480  |  Size: 102 KiB

BIN
relay/attachments/5v-relay-pins-layout.png View File

Before After
Width: 1280  |  Height: 598  |  Size: 120 KiB

+ 20
- 0
relay/attachments/main-proj-architecture.dot View File

@ -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;
}
}

BIN
relay/attachments/main-proj-architecture.png View File

Before After
Width: 368  |  Height: 272  |  Size: 26 KiB

BIN
relay/attachments/pinout-terminal.png View File

Before After
Width: 490  |  Height: 720  |  Size: 38 KiB

BIN
relay/attachments/wiring-diagram-relay.png View File

Before After
Width: 1756  |  Height: 842  |  Size: 887 KiB

+ 287
- 0
relay/rtr-relay.md View File

@ -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.)

Loading…
Cancel
Save