---
# The documents this driver was written against (handbook ADR-0019), and where the driver relies on them.
# Never commit a PDF: `sha256` identifies the exact file that was used, so a reader can confirm they hold the same
# revision. `pdf` is a stable direct link when the vendor publishes one; otherwise readers download from `url`.
#
# The README card, docs/datasheet.md and the "Datasheet" box on each page are generated from this file by
# tools/docs/generators/datasheet.py (`kokeb-docs gen`).
#
# The driver is generic: it knows no thermistor part. Two documents stand behind it.
#
#   beta  Not a vendor document: the beta equation, the Steinhart-Hart equation and the voltage divider. Everything
#         generic in the driver (the conversion, the interpolation, the divider, the error bounds) is derived from
#         these and checked against an independent model in tests/, never against a datasheet.
#   ds    The worked example only: the datasheet of one part, the TDK NTCG163JF103FT1S (one page, Rev.3, 8 May
#         2023, no document number printed). It confirms R25, B25/50, B25/85, the tolerances, the power rating, the
#         dissipation constant, the current and voltage limits, the operating range and the package. It does NOT
#         print the resistance table: the sheet links a separate 1 degC step file (rt_sheets/ntcg163jf103ft1s.csv)
#         that answers 403 to an automated fetch, so the 39 rows of the preset are still unverified.
#         Nothing generic depends on this document.
documents:
  - id: beta
    vendor: Public references
    title: Beta equation, Steinhart-Hart equation and the voltage divider
    kind: Reference
    number: "n/a"
    revision: "n/a"
    date: "n/a"
    url: https://en.wikipedia.org/wiki/Steinhart%E2%80%93Hart_equation
    pdf: null
    page_offset: 0
    sha256: "n/a (a web page, not a file)"
  - id: ds
    vendor: TDK
    title: Chip NTC Thermistor, NTCG series, NTCG163JF103FT1S (datasheet)
    kind: Datasheet
    number: "none printed"
    revision: "Rev.3"
    date: "May 8, 2023"
    url: https://product.tdk.com/system/files/dam/doc/product/sensor/ntc/chip-ntc-thermistor/data_sheet/datasheet_ntcg163jf103ft1s.pdf
    pdf: https://product.tdk.com/system/files/dam/doc/product/sensor/ntc/chip-ntc-thermistor/data_sheet/datasheet_ntcg163jf103ft1s.pdf
    page_offset: 0
    sha256: "64d2925d33b75da76b13e498fa5e889def95b02ba72059528f05820585284fd4"

# One row per thing the driver takes from a document: the section names and page numbers, the driver API that
# implements it, and the docs pages that explain it (file names in docs/). Generic rows cite the `beta` reference
# (page 1: a web page has none). The `ds` rows cite the sheet's own headings on its only page.
topics:
  - topic: "Beta equation and the B25/85 pair"
    doc: beta
    section: "Beta model, 1/T = 1/T0 + ln(R/R0) / B"
    page: 1
    driver: "`Curve::r0_ohm`, `b_kelvin`, `b_t2_mc`, `presets::kGeneric10kB3950`"
    docs: [conversion, presets, configuration]
  - topic: "Steinhart-Hart and the table tool"
    doc: beta
    section: "Steinhart-Hart, 1/T = a + b ln R + c ln(R)^3"
    page: 1
    driver: "`Curve::sh_a_e15`, `sh_b_e15`, `sh_c_e15`, `Curve::table`, `tools/ntc_table.py`"
    docs: [conversion, presets]
  - topic: "Voltage divider and the series resistor"
    doc: beta
    section: "Divider, V = V_s R_n / (R_s + R_n)"
    page: 1
    driver: "`Config::topology`, `series_ohm`, `adc_vref_mv`, `divider_supply_mv`, `Convert()`"
    docs: [hardware, conversion, configuration]
  - topic: "Self-heating power"
    doc: beta
    section: "Dissipated power, P = V_s^2 R_n / (R_s + R_n)^2"
    page: 1
    driver: "`SelfHeatingMicrowatts()`"
    docs: [hardware, api-guide]
  - topic: "Example part: R-T table (rows unverified)"
    doc: ds
    section: "Electrical Characteristics, 1degC Step Data link (the table itself is not in the PDF)"
    page: 1
    driver: "`presets::kTdkNtcg163jf103ft1sRows`, `kTdkNtcg163jf103ft1s`"
    docs: [presets, worked-example]
  - topic: "Example part: R25, B and tolerances"
    doc: ds
    section: "Electrical Characteristics: Resistance, B value"
    page: 1
    driver: "`Curve::r0_ohm`, `b_kelvin`, `b_t2_mc`, `r_tol_ppm`, `b_tol_ppm`"
    docs: [presets, worked-example]
  - topic: "Example part: package and ratings"
    doc: ds
    section: "Dimension and Construction; Electrical Characteristics: power, dissipation, current, voltage, range"
    page: 1
    driver: "`SelfHeatingMicrowatts()` (the dissipation constant is yours to supply)"
    docs: [worked-example, hardware]
