; ----------------------------------------------------------------------------
;
; Title:
;
;   PP07 -- 10 MHz "picPET" PIC-based Precision Event Timer (both edges)
;
; Function:
;
;   This program runs on a 8-bit 8-pin PIC microcontroller and implements a
;   Precision Event Timer (PET) -- a modest and inexpensive version of a
;   continuous time-stamping counter, or time-to-digital converter (TDC).
;
;   Given an accurate 10 MHz clock into pin2, periodic edge trigger events
;   on pin5 are time-stamped to sub-microsecond resolution. The readings
;   are output as simple ASCII messages over RS232 on pin3 to a host (PC)
;   for display, logging, plotting, or statistical analysis. Single or average
;   time interval (period), time error (phase), pulse rate (frequency), or
;   pulse width measurements can be made from the raw data set.
;
;   Typical uses are to time safely isolated mains frequency zero crossings,
;   or turns of a bicycle wheel, swings of a pendulum clock, rotations of an
;   analog power meter, pulses from a digital kWh meter, engine tachometer
;   signals, drips from a faucet, ticks from a quartz oscillator, or human
;   heart beats. A picPET can be used as a time stamping counter (TSC) or
;   frequency counter (about 7 digits/second).
;
;   Time-stamp resolution is 100 ns, granularity is 400 ns, precision is
;   about 10 ps, and accuracy is equal to the accuracy of the 10 MHz clock.
;
;   This picPET is for optical detector pulses (pendulum clock measurement):
;   - Period or beat time is delta of leading edge to leading edge.
;   - Velocity is based on delta of leading edge to trailing edge.
;   - True center time is mean of leading edge and trailing edge.
;   - Tilt or swing symmetry is ratio of even beat to odd beat.
;
;   In this version:
;
;   - Each measurement is a 12 digit time-stamp of leading edge, a 2 digit
;     event count, and a 12 digit time-stamp of trailing edge.
;
;   - Config: positive or negative pulse polarity.
;
;   - Config: normal or inverted serial output.
;
;   - The power-up "hello" output is delayed by 2 seconds to give host OS
;     or USB/serial adapters time to settle.
;
;   - The time-stamp is set to zero on the first event after power-up.
;
;   - Event processing overhead (including serial transmit time) is exactly
;     25 milliseconds so the peak rate is 40 samples per second.
;
;   - For clean results, input pulse width should be greater than 0.5 ms.
;     Note that pendulum pulses typically have widths of 2 ms to 200 ms.
;
; Diagram:
;
;                                ---__---
;                5V (Vdd)  +++++|1      8|=====  Ground (Vss)
;            10 MHz input  ---->|2  pP  7|<+---  Pos(1) Neg(0) pulse
;            RS232 output  <----|3  07  6|<+---  Zero-sync(0)
;         RS232(0) TTL(1)  o--->|4      5|<----  Event pulse input
;                                --------
;
;   - GP0/pin7 (WPU) configures pulse polarity. Leave high for positive pulse
;     (low-high-low). Pull to ground for negative pulse (high-low-high).
;     Note the pin is read once only at power-up.
;
;   - GP1/pin6 (WPU) allows optional counter clear or 1PPS synchronization.
;     Pull to ground and next event will reset time-stamp to zero.
;
;   - GP2/pin5 is event input (Schmitt trigger).
;
;   - GP3/pin4 controls serial output polarity. Ground for normal "true"
;     unipolar RS232. Set high for "inverted" serial (TTL, MAX232, FTDI).
;     Microchip says do not leave this pin floating.
;
;   - GP4/pin3 is serial output, 19200 baud.
;
;   - GP5/pin2 is clean precise digital 10 MHz clock input.
;
;   - Vdd may be 2.0 to 5.5 VDC. See PIC 12F675 datasheet for details.
;
; Theory:
;
;   A wide BCD counter in a 10 kHz isochronous loop accumulates elapsed
;   time in 100 us units. The 8-bit TMR1L register tracks cpu cycles (250)
;   within that loop. The 8-bit TMR0 register counts pulses on pin5. At the
;   point an edge-triggered interrupt occurs, a snapshot of these registers
;   is made and later used to calculate the precise time-stamp of the event.
;
;   The code is isochronous (all code paths take exactly the same number of
;   cycles under every possible condition) and elapsed time is kept not by
;   hardware timers but by isochronous CPU code execution.
;
;   There is no software jitter, no interrupt jitter, and hardware sampling
;   jitter is a few ps. Time-stamp granularity is 1 Tcy (400 ns). The main
;   loop is compensated for interrupt time, including the so-called dummy
;   cycles that give PIC its cycle-consistent interrupt response. With this
;   design no cycles are ever lost and measurements are as accurate as the
;   time/frequency accuracy of the 10 MHz clock itself.
;
;   Traditional interval timers measure *from* A *to* B, then C to D, then
;   E to F, etc. By contrast a continuous time-stamping counter measures
;   the time *of* A, of B, of C, D, E, and so on. It allows one to compute
;   B-A, C-B, D-C, E-D, or E-C, C-A, or even E-A, etc. This flexibility,
;   no time drift, and zero deadtime between measurements makes TSC (time
;   stamping counters) more attractive than TIC (time interval counters)
;   for some applications.
;
;   Host software handles the 256 (0x100 hex) event counter wrap-around
;   and 100 or 100000 (decimal) second elapsed time counter wrap-around.
;
;   Note that TS (time-stamp) data can be converted into TI (time interval)
;   data by pairwise subtraction.
;
;   In normal operation the event count may be ignored since it increments
;   by exactly 0x01 for each measurement.
;
;   Blanking occurs while a time-stamp is being output to the PC, however
;   any events that happen to occur during this window are still counted.
;
;   Although the code will precisely time rising and/or falling edges it
;   is not well suited for very narrow pulses or high pulse rates.
;
;   If verbose time-stamps are required (such as dates or local/UTC time),
;   then host software combines its own less stable OS clock with the
;   precise PIC time-stamps to create UTC absolute time-stamps. For many
;   applications only differential seconds (time interval) is needed and
;   that is simply pair-wise subtraction of adjacent time-stamps.
;
;   For more information see http://www.leapsecond.com/pic/
;
; Version:
;
;   23-Nov-2017  Tom Van Baak (tvb)  www.LeapSecond.com
;
; ----------------------------------------------------------------------------

PICPET_PID  equ     0x07        ; picPET product id
PICPET_VID  equ     0x10        ; firmware version number