gex-docs/UNIT_FCAP.md

# Frequency / Pulse measurement

- Frequency measurement
  - Direct method (counting pulses in a time period)
  - Indirect method (measuring a single pulse)
- PWM measurement - Indirect method also reports duty cycle
- Single pulse measurement
- Free-running pulse counter

### Direct vs Indirect method

The direct method works well for a wide range of frequencies, from Hz to tens of MHz. For
very high frequencies, a prescaller can be enabled. This method has a best-case
resolution of 1 Hz, which could be increased by extending the measurement time, which
already needs to be long, usually 1 second or more for low frequencies.

The indirect method has a sub-Hz resolution and is much faster than the direct method for
low frequencies. It can be used for signals up to tens of kHz, while the direct method
can handle 20 MHz or more without issues.

*NOTE:* The accuracy of all measurements is dependent on the system clock speed.
To measure the system clock using an external counter, you can output it on a pin using
the MCO function configured in `SYSTEM.INI`.

### Burst vs Continuous

Both the direct and indirect methods can operate in a free-running or burst mode.

- Burst mode performs one or several measurements (with averaging if using the indirect method).
- Free-running (continuous) mode performs periodic measurements without averaging.
  The advantage is that the last measurement is always immediately available for read-out, without having to wait for the emasurement.

## Commands

### STOP (0)

Stops all ongoing measurements.

### INDIRECT_CONT_START (1)

Start a free-running frequency / duty cycle measuring using the indirect method.

### INDIRECT_BURST_START (2)

Start a burst of indirect measurements.
Waits for the next rising edge before starting the measurements.

*Request:*
- u16 - number of pulses to average

*Response:*
- u16 - core speed in MHz
- u16 - number of pulses
- u64 - sum of all periods (in core ticks)
- u16 - sum of all on-times (positive interval of the pulse)

GEX avoids using float here to reduce code size and avoid floating
point errors. To get the period, use `period_sec = periods / (mhz * 10e6 * count)`

Frequency is `freq = 1 / period`.

The average duty cycle is `duty = ontimes / periods`

### DIRECT_CONT_START (3)

Start repeated measurement using the direct method.

*Request:*
- u16 - measurement time (ms)
  - 0 = no change
  - default 1000, configurable in the unit settings
- u8 - prescaller (1,2,4,8)
  - 0 = no change
  - default 1, configurable in the unit settings

### DIRECT_BURST_START (4)

Start a single direct measurement (pulse counting) over
a given time period. Longer periods can be used for higher precision
using averaging.

*Request:*
- u16 - measurement time (ms), often 1000 (=1s)
- u8 - prescaller (1,2,4,8)
  - 0 = no change
  - default 1, configurable in the unit settings

*Response:*
- u8 - prescaller (1,2,4,8)
- u16 - measurement time (ms)
- u32 - pulse count

Calculate the frequency by `freq = (1000 * count * presc) / time_ms`.

### FREECOUNT_START (5)

Clear and start the free-running pulse counter.

*Request:*
- u8 - prescaller (1,2,4,8)
  - 0 = no change
  - default 1, configurable in the unit settings

### MEASURE_SINGLE_PULSE (6)

Measure a single pulse on the input. Waits for a rising edge.

*NOTE:* The result may be inaccurate if the input is High when starting the measurement.

*Response:*
- u16 - core speed in MHz
- u32 - pulse length (core ticks)

### FREECOUNT_CLEAR (7)

Clear the free-running counter while retrieving the current value.
Normally no pulses should be missed, but please be aware that this
operation is not atomic and glitches can occur at high frequencies.

*Response:*
- u32 - last counter value

### INDIRECT_CONT_READ (10)

Read the latest result from the continuous indirect method measurement
(measurement of individual pulses).

*Response:*
- u16 - core speed in MHz
- u32 - period (core ticks)
- u32 - on-time (positive interval of the pulse)

Duty cycle is `duty = ontime / period`.
Period `period_sec = period / (mhz * 10e6)`.
Frequency `freq = 1 / period_sec`.

### DIRECT_CONT_READ (11)

Read the latest result from the continuous direct method measurement (pulse counting).

*Response:*
- u8 - prescaller (1,2,4,8)
- u16 - measurement time (ms)
- u32 - pulse count

Frequency is `freq = (1000 * presc * count) / time_ms`.

### FREECOUNT_READ (12)

Read the current value of the free-running pulse counter.

*Response:*
- u32 - counter value

### SET_POLARITY (20)

Set the measured pulse polarity.

*NOTE:* This is normally configured in the unit settings.
Changes done through this method are temporary, not persisted to flash. The same
applies to the other SET_* commands.

*Request:*
- u8 - active level (0,1)

### SET_DIR_PRESC (21)

Set prescaller for the direct mode measurement.

*NOTE:* This does not take effect until the direct measurement is restarted. (TODO: fix?)

*Request:*
- u8 - prescaller (1,2,4,8)

### SET_INPUT_FILTER (22)

Set input filtering (a hardware feature designed to ignore short glitches)

*Request:*
- u8 - digital filtering factor (0-15, 0=off)

### SET_DIR_MSEC (23)

Set direct measurement period.

*NOTE:* This does not take effect until the direct measurement is restarted. (TODO: fix?)

*Request:*
- u16 - period in milliseconds

### RESTORE_DEFAULTS (30)

Stop any measurement and restore all the run-time configurable settings to their default
values (as configured in the unit settings).