rtr-docs/light-meter/rtr-light-meter.md

# Return to Ritherdon: Light Meter

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.

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-proj-architecture](attachments/main-proj-architecture.png)

## Hardware Specifications

Here are the 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.)
- [Light
  Sensor](https://www.amazon.co.uk/s/ref=as_li_ss_tl?url=search-alias=aps&field-keywords=LDR&linkCode=ll2&tag=pimylifeup-21&linkId=8662811b5623ce86540420c7e8ce0268&language=en_GB)
  (I tend to use "light sensor" and "light meter" interchangeably --
  sorry if confusing)
- [2 x 1kΩ
  Resistor](https://www.amazon.co.uk/1K-Resistors-50-Pack-Electronics/dp/B00JGUE0L0)
- [330nF
  Capacitor](https://www.alibaba.com/product-detail/ODOELEC-334-0-33uf-330nf-50v_60626664828.html)
- 
[Breadboard](https://thepihut.com/products/raspberry-pi-breadboard-half-size)
  (Optional but recommended if you do not know how-to solder or you
  don't feel comfortable doing it)
- [Jumper
  Wires](https://thepihut.com/products/rpi-premium-jumper-wires-40pk-male-female-100mm?_pos=18&_sid=4d08c5200&_ss=r)
  (I'm assuming you are using the breadboard. If are not, you might
  need different cables like Female-to-Female or ones without a
  connector on the ends)

### Raspberry Pi Technical Specifications

The information below was taken from [Raspberry Pi
Foundation](https://www.raspberrypi.org/products/raspberry-pi-4-model-b/specifications/)'s
website.

- Broadcom BCM2711, Quad core Cortex-A72 (ARM v8) 64-bit SoC @ 1.5GHz
- 2GB, 4GB or 8GB LPDDR4-3200 SDRAM (depending on model)
- 2.4 GHz and 5.0 GHz IEEE 802.11ac wireless, Bluetooth 5.0, BLE
- Gigabit Ethernet
- 2 USB 3.0 ports; 2 USB 2.0 ports.
- Raspberry Pi standard 40 pin GPIO header (fully backwards compatible with previous boards)
- 2 × micro-HDMI ports (up to 4kp60 supported)
- 2-lane MIPI DSI display port
- 2-lane MIPI CSI camera port
- 4-pole stereo audio and composite video port
- H.265 (4kp60 decode), H264 (1080p60 decode, 1080p30 encode)
- OpenGL ES 3.0 graphics
- Micro-SD card slot for loading operating system and data storage
- 5V DC via USB-C connector (minimum 3A*)
- 5V DC via GPIO header (minimum 3A*)
- Power over Ethernet (PoE) enabled (requires separate PoE HAT)
- Operating temperature: 0 – 50 degrees C ambient

**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)

## Project Set-Up

Light Meter 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 the required software dependencies
onto the operating system and any 'maintenance' tasks for sustained
use of the device (whilst in operation). For the actual code written
specifically for this project, please refer to the [project's
code repository](https://git.abbether.net/return-to-ritherdon/light-meter).

### 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 "factory#" (where "#" is a number between 1 and 3).
- 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 the 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 the 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)

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
entering the "Network Options" section. For the other ways of
connecting to a wireless network, I recommend you read the tutorial
because it can get complicated and the options are numerous.

#### Light-Meter Set-Up

The light-meter is a custom addition to the Raspberry Pi which is
built using the Pi's general-purpose input and output (G.P.I.O.)
pins. You can see the layout of the components connected to the Pi in
the diagram below.

![hardware-layout](attachments/hardware-layout.png)

Depending on the type of enclosure you use, you might find it more
convenient to have the actual light-meter (component) connected to the
breadboard with a pair of jumper wires. To help explain the point,
please see the image below.

![light-meter-extension](attachments/light-meter-extension.png)

#### Power Supply

I am under the impression this device will run in a fully functional
building (I.E. the Ritherdon factory). Because of this, I have taken
no precautions or steps to assume a loss of power beyond the typical
scenarios found in a U.K. factory environment. I have no idea how the
Pi will operate whilst powered via batteries or other "mobile" power
sources. With that said, make sure you can place the Pi where you want
it whilst still being able to power it.

The Raspberry Pi should be programmed to turn itself off at a
designated time. At the time of writing it is expected to be around 6
P.M. with a plug with a timer cutting all power to the Pi
approximately 30 minutes after that (when the factory usually powers
down for the day). When the factory's electrics are turned on at the
start of a working day, the Pi will be included in that process. It
will require no intervention from any of the workforce -- apart from
the initial factory start-up process.

### 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/light-meter/`. From
there, run the following command,

```bash
# This must be the first thing you run after you have cloned
# the repository.
. ~/repos/light-meter/make-log-files.sh
```

You can test the code is working properly by running it. You can do
that by entering `sudo python3 ~/repos/light-meter/cli_meter.py` into
the console. This is assuming the server specified in "cli_meter.py"
is set-up and working as intended.

**Note: For some reason, I had trouble running "cli_meter.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.**

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/light-meter/startup.sh &
00 18 * * * /home/rtrp/repos/light-meter/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 "cli_meter.py"
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
sending light 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.)

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/light-meter/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

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