# Compensating Development Timer

Developing traditional film and silver paper is very temperature
dependent.  The warmer the developer solution, the less time the film
or paper needed to be developed and vice-versa.  Historically, people
read the temperature and then manually corrected their development
time accordingly, using a correction table provided by the
manufacturer.

It turns out that these corrections for temperature are quite similar
across different manufacturers of film and paper, although the
corrections *are* different for film *versus* paper.

Many years ago, a company called "Zone VI" realized this and created
an analog timer that corrected for this effect.  You placed a
temperature probe into the developer and it corrected - via analog
adjustments - what a "virtual second" actually had to be.  The
photographer just looked up the normal development time for 68F
developer and the timer ran faster or slower based on the actual
temperature.  Better still, if the temperature of developer varied
*during* development, it corrected for that in realtime.  The Zone VI
Compensating Timer had settings for film, paper, and realtime.

The timer was a work of genius engineering and a really nice
addition to the serious photographer's wet dakroom.  I've depended
on one of these for years to make my darkroom work repeatable
with minimal thinking or measuring.  Mine is getting kind of old
now and I began to wonder what I would do if it broke.  The timer
did come with a "Lifetime Warranty",  Sadly Zone VI and
its founder, Fred Picker, are both now long gone making warranty
claims ... difficult.

While I could design an analog replacement or just figure out the
circuit of the Zone VI, it occurred to me that it would be easier to
just design a "work alike".  Thanks to the explosion of interest
in robotics and the Internet Of Things, there is an embarassment
of riches of computers, sensors, switches, temperature probes,
and so forth.  Not only can we build something like this ourselves,
doing so has several advantages over the old Zone VI timer:

* It's digital, not analog, so we don't have mess with
  a bunch of precision parts and corrective feedback circuits.

* It's software controlled so you can customize how this timer works
  to suit you.  Don't like my compensation factors?  Want to adapt
  this for a different application?  Both are easily done with
  software changes.

* It's cheap.  You can build one of these for well under $50.  (The
  original Zone VI timer was around $200 if memory serves, and that
  was when money was still worth something. :)


## Required Skill Level

As of this writing, you'll need to be an accomplished Raspberry Pi
hacker or have access to someone who is.  The goal is to eventually
package this up in a way that a relatively inexperienced person could
build it, but I wanted to make the code and design available as early
as possible for those who have have already expressed an interest in
this project.


## State Of The Project

The hardware design is really simple because it's based on
a Raspberry Pi Zero platform.  The whole timer uses a little
over a dozen parts in total ... that's including a case and
USB power supply.

The code here on the master branch should be considered
stable and usable.

## Basic Hardware Connections

The code will tell where to connect things on a Raspberri Pi Zero.

*Note that these reference GPIO pin numbers, not device pin numbers.*

A few notes:

* Where there are pullups or references to Vcc below, I've
  chosen to use a 5V pin on the Raspberry Pi Zero.

* You'll need two TM1637-compatible 4-digit LED displays - one
  for time and one for temp.  Their CLK and DIO assignments
  are noted in the code.  Of course, you'll also have to
  connect them to Vcc and ground.

* Connect a piezo buzzer between GPIO 26 and ground.  No resistor
  needed.

* Connect a momentary contact footswitch between GPIO 6 and ground.
  Pull up that pin with a 4.7K resistor.

* Connect a SPDT switch for profile selection to GPIO pins 23 and 24,
  each pulled up with a 4.7K resistor.  The switch common goes to
  ground.

* Connect the data line of a DS18B20 temperature probe to GPIO 4,
  pulling it up with a 4.7K resistor. Again, you'll have to connect
  it to Vcc and ground as well.

* Take note to read the code concerning the temperature probe.
  Each probe has a unique serial number and you have to configure
  a symlink in Linux to point to your specific device.


## Basic Software Setup

There's not much to this:

* Get your favorite Raspberry Pi Linux distro running.

* Setup 1-wire support.  In `/boot/config.txt` set `dtoverlay=w1-gpio`
  (At least, that's how you do it on Raspbian.  Other distros may be
  different.)

* Make sure python3 is installed - this project requires it.

* Make sure to properly create the symlink to the temperature
  probe as described in the code.

* pip3 install the wiringpi module.  You can either do this
  systemwide or in a pew virtual environment.  Either way,
  you need to be `root` because this code - at least for now -
  requires superuser to run.

* Copy the `devtimer.py` and `tm1637.py` files onto your
  Pi Zero.  You can then start the timer with `./devtimer.py`.

* By default, the code currently writes a lot of debug info to
  the Pi's tty so you can watch all manner of things fly by.
  If it bugs you, just change `DEBUG` to `False` at the top of the
  code.


## Operating The Timer

* You can add a reference to `/etc/rc.local` to automatically start the
  timer when the Pi boots.   Right now, this takes about 30 seconds but a
  future effort will work to rip out the stuff not needed and make booting
  way faster (hopefully).

* At program start, the temperature display will briefly show 999F.
  This is a "sentinel" to let you know the timer is looking for the
  temperature probe.  The display should rapidly update to show actual
  temperature as reported by the probe.  If it does not (i.e., 999F
  remains displayed), it means that something is wrong with the
  temperature measurement hardware.

* Pressing the momentary contact footswith start/resets the timer.

* The SPDT switch selects Film correction, Paper correction, or
  realtime (no correction).  You can change this while the timer
  runs.

* When the film profile is selected, the displays are dimmed on the
  assumption that film is panchromatic (it can "see" red) and far more
  sensitive to light than paper.

* If you are in a film or paper correction profile, and the
  temperature is beyond the range of the timer to correct, the
  temperature display will blink.  This lets you know the timer is not
  capable of correcting for temperatures in that range.  This does
  not happen in the realtime profile.  There is also an audible
  alert (see below.)  Both the blinking and the audible alerting
  take place whether the timer is actually running- or not.  This
  is intentional to make you take action.  If you want to
  do compensating timing, you have to get the temperature back
  in range.  If not - say, you just want to measure temperature -
  then you should switch to the realtime profile.


## Sounds

* The timer "chirps" at startup to let you know it is initializing.

* The timer beeps twice each time you start- or stop the timer.

* The timer provides a single beep at each virtual 30 second
  mark.

* In film or paper correction profiles, if the temperature
  is beyond the range of the timer to correct, you will hear
  5 short beeps repeated.

## Calibration And Tuning

The timer should pretty much be ready to run "out of the box".  But,
here are a few ideas on how it can be tuned or adjusted:

* VERY IMPORTANT: Do **NOT** run the timer with `DEBUG = True`. This
  option is for the sofware developer only and introduces extra
  output that *makes the timer less accurate*.  So, unless you are
  hacking on the hardware or software, leave this set to `False`.

* The `CALIBRATION_OFFSET` variable is designed to help compensate for
  the amount of time the master timing loop needs to run on your
  particular platform.  The default value should be about right for a
  Raspberry Pi Zero.  If you use a different platform or overclock
  your Pi, you may wish to adjust this to calibrate the timer.  This
  is best done by running the timer in realtime mode (no temperature
  compensation), adjusting this variable and seeing how the timer
  speed compares to a known good reference timer.

* You can adjust the individual compensation entries for film or paper
  to your liking. The values there are pretty good first
  approximations based a fair bit of research, but you can "tweak"
  them to suit your style of photography and film development.


## Help & Support

There isn't any.  You can send mail to `devtimer@tundraware.com` and I'll
do what I can to help as I able, but this is very much a part-time activity.

What would be VERY welcome would be pull requests, bug reports, patches, etc.