================================================================================
 SPDM 1 Speedometer Replacement Board
 Ferrari 208/308 Series and Ferrari 512 Type 1 Speedometers
================================================================================

Archive release:   1.9
Firmware version:  1.9
Hardware revision: 1.6

Hardware and documentation license:
  Creative Commons Attribution 4.0 International (CC BY 4.0)

Firmware license:
  GNU General Public License Version 3 (GPL v3)

Author:   Adrian Le Hanne <info@dinoplex.org>
Website:  www.dinoplex.org


Contents
--------
  1. Introduction
  2. Build the Hardware
  3. Use Compiled Images and Flash
  4. Build Your Own Images and Flash
     4.1 Firmware Configuration
     4.2 Tire Size and Odometer Calibration
     4.3 Toolchain Setup
     4.4 Building and Flashing
  5. Install the Board
  6. Needle Calibration
  7. Licensing
  8. Support


--------------------------------------------------------------------------------
1. INTRODUCTION
--------------------------------------------------------------------------------

This archive contains the hardware Gerber files, firmware, and documentation for
the SPDM 1 replacement circuit board. It replaces the original electronics
in Veglia Type 1 electronic speedometers while retaining the original
instrument housing, mechanism, connectors, and appearance.

The design is intended for Veglia Type 1 speedometers used in the following
Ferrari models:

  - Ferrari 208/308 GT4, EU and US versions, 1974-1980
  - Ferrari 208/308 GTB/GTS, EU and US versions, 1976-1980
  - Ferrari 308 GTBi/GTSi, US versions, 1980-1981
  - Ferrari 308 Quattrovalvole (QV), early US versions, 1982

Ferrari 512 instruments using the same Veglia Type 1 electronics are
supported by the design, but this application has not yet been tested in a
vehicle.

Later Veglia speedometers fitted with Type 2 or Type 3 circuit boards are
not compatible with this replacement board.

The board can be used for:

  - replacing defective original electronics
  - retaining normal mph or km/h operation
  - converting an mph instrument to km/h operation
  - operating with the later Type 2 sender after a gearbox or sender change
  - adapting the odometer calibration for supported or custom tire sizes

An mph-to-km/h conversion also requires a suitable km/h dial face.

The firmware drives:

  - the analog speedometer needle coil from the incoming VR sender pulses
  - the mechanical odometer stepper motor through a configurable pulse divider

The firmware uses a doubled coil drive pulse rate compared to the original
circuit for smoother, jitter-free needle movement at low speeds.

Target microcontrollers:
  Atmel/Microchip ATtiny25, ATtiny45, or ATtiny85

The ATtiny25 is the recommended default build target as the firmware footprint is quite small.

The archive is organized around the following main items:

    .
    |-- README.txt                    This file
    |-- firmware/                     Firmware source and build tooling
    |   |-- Makefile                  Build and flash automation
    |   |-- main.c                    Firmware source and configuration
    |   `-- compiled_images/          Ready-to-flash firmware images
    |       `-- Standard/main.hex     Default Sender Type 1 build
    |-- hardware/                     PCB Gerber files and the BOM
    `-- installation/                 PDF file explaining the installation

Start with this README for the hardware and firmware workflow and use the
installation documentation for instrument disassembly, installation, and
mechanical access details.

The recommended workflow follows the order of this README:

  1. Build and assemble the hardware (section 2).
  2. Flash the firmware, either using a compiled image (section 3) or a
     self-built image (section 4).
  3. Install the board in the instrument (section 5).
  4. Calibrate the speedometer needle (section 6).


--------------------------------------------------------------------------------
2. BUILD THE HARDWARE
--------------------------------------------------------------------------------

The circuit boards can be produced from the Gerber files in the "hardware"
directory. The files are provided in two supported formats:

  - Gerber RS-274X
  - Gerber X2 (newer format with embedded attributes)

Use the format preferred by your PCB manufacturer; both describe the same
board. Most manufacturers accept either, while Gerber X2 is recommended
where supported.

To build the board:

  1. Have the PCB manufactured from the supplied Gerber files.
  2. Source the electronic components (SMD, THT) listed in the Bill of
     Materials in the "hardware" directory.
  3. Assemble the PCB, either manually or through a professional PCB
     assembly service.
  4. Inspect and electrically test the completed board.

Building the board requires experience with SMD soldering and electronic
assembly. Alternatively, the complete PCB manufacturing and assembly process
can be outsourced to an Electronic Manufacturing Services (EMS) provider.

All electronic SMD components were selected based on both electrical requirements 
and strong market availability to ensure reliable sourcing. Standard components, 
such as resistors and capacitors, can generally be replaced with equivalent parts 
of similar specifications.

--------------------------------------------------------------------------------
3. USE COMPILED IMAGES AND FLASH
--------------------------------------------------------------------------------

This is the fastest way to program a standard board using Sender Type 1,
without unit conversion and without compiling the firmware.

If the firmware configuration does not need to be changed, a compiler is
not required. The "firmware/compiled_images" directory contains
ready-to-flash .hex files for the supported configurations, organized in one
subdirectory per configuration.

For example:

    firmware/compiled_images/Standard/main.hex

This image uses the default TYPE1_SENDER1 ("Normal") configuration.

Requirements:
  - avrdude installed (see section 4.3 for installation commands;
    the compiler packages are not required for this workflow)
  - an ISP programmer connected to the board's ISP header
  - a new, blank, or correctly configured ATtiny25/45/85

IMPORTANT:
On a new or blank microcontroller, the fuses must be programmed before the
firmware image is flashed.

1. Set the fuses. This is required once for each new or blank chip:

    avrdude -c avrispmkII -P usb -p attiny25 \
      -U lfuse:w:0x62:m -U hfuse:w:0xdf:m -U efuse:w:0xff:m -B 22

   Alternatively, using the Makefile from the firmware directory:

    cd firmware
    make fuse

2. Flash the compiled standard image. For the standard configuration, run
   this command from the archive root:

    avrdude -c avrispmkII -P usb -p attiny25 \
      -U flash:w:"firmware/compiled_images/Standard/main.hex":i

The board is now ready for installation (section 5) and calibration
(section 6).

Fuses normally need to be programmed only once per chip unless they are
deliberately changed later.

Adjust the -c and -P parameters when using a different programmer or port.

If the speedometer uses Sender Type 2, requires mph-to-km/h conversion, or
needs a different tire size, build your own image as described in section 4.


--------------------------------------------------------------------------------
4. BUILD YOUR OWN IMAGES AND FLASH
--------------------------------------------------------------------------------

4.1 Firmware Configuration
--------------------------

Before compiling, open firmware/main.c and select exactly one configuration
in the "Config Section" near the top of the file by uncommenting the matching
#define.

Default configuration:

  "Normal"
  TYPE1_SENDER1
      Standard mph or km/h speedometer using Sender Type 1.

Other supported configurations:

  TYPE1_SENDER1_MILES_TO_KMH_CONVERSION
      Converts an mph speedometer to km/h operation.
      A suitable km/h dial face is also required.

  TYPE1_SENDER2
      Standard speedometer using Sender Type 2.
      Sender Type 2 produces twice the pulse rate of Sender Type 1.

Only one configuration may be active at a time. Selecting more than one
configuration, or selecting none, may still allow the firmware to compile
but can produce incorrect speed and odometer calibration. Check compiler
warnings before flashing.


4.2 Tire Size and Odometer Calibration
--------------------------------------

The odometer calibration is determined by the rear tire rolling
circumference and the selected sender configuration.

The supplied firmware supports the following standard tire sizes:

  - 205/70 VR14
  - 220/55 VR390 TRX
  - 225/50 R16

The default tire size is 205/70 VR14 for the compiled binaries.

Custom tire sizes can be supported by changing the rolling-circumference or
odometer-divider setting in the firmware configuration section. Use the
comments in firmware/main.c to identify the applicable setting and required
units.

Measure or calculate the loaded rolling circumference carefully. An
incorrect value will cause cumulative odometer error even if the speedometer
needle has been calibrated correctly.

The rolling circumferences of the three factory tire sizes differ by less
than 3%, so this setting normally does not need to be changed unless maximum
odometer accuracy is required.


4.3 Toolchain Setup
-------------------

To compile and flash the firmware, install:

  - avr-gcc and avr-libc
  - avrdude
  - GNU Make

An Atmel-ICE, AVRISP mkII, or compatible AVR ISP programmer is required.

--- Linux: Debian or Ubuntu ----------------------------------------------------

    sudo apt update
    sudo apt install gcc-avr avr-libc avrdude make

--- Linux: Fedora --------------------------------------------------------------

    sudo dnf install avr-gcc avr-libc avrdude make

--- Linux: Arch ---------------------------------------------------------------

    sudo pacman -S avr-gcc avr-libc avrdude make

--- macOS: Homebrew ------------------------------------------------------------

    brew tap osx-cross/avr
    brew install avr-gcc avrdude make

The discontinued CrossPack-AVR package should not be used for new setups.

--- Windows -------------------------------------------------------------------

Recommended:
Use Windows Subsystem for Linux (WSL) with a Debian or Ubuntu distribution
and follow the Linux instructions above. USB passthrough may be configured
with usbipd-win.

Alternative native Windows setup:

  - Install the AVR toolchain through Microchip Studio or a standalone
    avr-gcc/avr-libc distribution.
  - MSYS2 may be used to install the required command-line tools.
  - For an AVRISP mkII, install a compatible libusb driver with Zadig so
    avrdude can access the programmer.

Verify the installation:

    avr-gcc --version
    avrdude -v


4.4 Building and Flashing
-------------------------

The Makefile is located in the firmware directory. Connect the ISP programmer
to the board's ISP header before running an avrdude-based target.

    cd firmware

--- First installation on a new or blank microcontroller -----------------------

    make install

This target programs the required fuses first, then compiles and flashes the
firmware in the correct order.

--- Subsequent firmware updates ------------------------------------------------

    make flash

The fuses normally do not need to be programmed again.

--- Individual targets ---------------------------------------------------------

    make            Compile only and produce main.hex
    make fuse       Program the fuses only
    make flash      Compile if required and flash main.hex
    make cpp        Run the preprocessor on main.c
    make clean      Remove generated build files

The "make cpp" target is useful for confirming which configuration #define
is active.

--- Changing the programmer ----------------------------------------------------

The default programmer is an AVRISP mkII connected by USB. To use a
different programmer, edit the PROGRAMMER variable in the Makefile.

Examples:

    PROGRAMMER = -c usbasp
    PROGRAMMER = -c stk500v2 -P /dev/ttyUSB0


--------------------------------------------------------------------------------
5. INSTALL THE BOARD
--------------------------------------------------------------------------------

Before installation:

  1. Verify that the board is correctly assembled and free of solder bridges.
  2. Confirm that the correct sender and unit configuration is selected.
  3. Program the microcontroller fuses before flashing a new or blank device.
  4. Calibrate the speedometer needle as described in section 6.
  5. Confirm odometer operation and needle response before road use.

Follow the illustrated installation guide included in the "installation" folder:

  - removing the original circuit board
  - installing the replacement board
  - starting the calibration mode
  - adjusting the needle calibration trimmer


--------------------------------------------------------------------------------
6. NEEDLE CALIBRATION
--------------------------------------------------------------------------------

The speedometer needle must be calibrated after the replacement board is
installed.

To enter calibration mode:

1. Switch off power to the speedometer.
2. Fit the jumper across the marked calibration position on the
   board's 3 x 2 connector (Pin 4 & 6). Do not bridge any other pins.
3. Apply power.

When SW1/PB0 is held low during power-up, the firmware enters calibration
mode and generates an internal reference signal equivalent to:

  - 130 km/h for a km/h dial face
  - 81 mph for an mph dial face

Adjust the onboard trimmer until the needle indicates the appropriate value
for the installed dial face.

To leave calibration mode:

1. Switch off power.
2. Remove the calibration jumper.
3. Apply power again and verify normal operation.

The board remains in calibration mode until power is cycled with the jumper
removed.


--------------------------------------------------------------------------------
7. LICENSING
--------------------------------------------------------------------------------

Hardware design files and documentation
---------------------------------------

The hardware design files, PCB production files, and documentation are
licensed under the Creative Commons Attribution 4.0 International license
(CC BY 4.0):

    https://creativecommons.org/licenses/by/4.0/

You may use, modify, manufacture, and distribute the hardware commercially,
provided appropriate attribution is retained.

Firmware
--------

The embedded firmware and associated source code are licensed under the GNU
General Public License Version 3 (GPL v3):

    https://www.gnu.org/licenses/gpl-3.0.html

You may use, modify, and distribute the firmware commercially. If you
distribute the firmware, including a modified version, you must comply with
GPL v3, including the applicable source-code and license-notice requirements.

The GPL license applies to the firmware; it does not change the CC BY 4.0
license applied to the hardware design files and documentation.

Trademarks
----------

This project is an independent open-source development and is not affiliated
with, endorsed by, or approved by Ferrari S.p.A. or Veglia Borletti. Ferrari
and Veglia names are used only to identify compatible vehicles and
instruments.

No warranty
-----------

This project is provided without warranty. Verify the assembled board,
firmware configuration, calibration, and vehicle installation before use.


--------------------------------------------------------------------------------
8. SUPPORT
--------------------------------------------------------------------------------

Questions and feature requests:

    info@dinoplex.org
