rtr-docs/eyes-and-ears/rtr-eyes-and-ears.md

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