{ "openapi": "3.1.1", "info": { "title": "Ohmforge Microcontroller Timing Calculator API", "version": "1.0.0", "summary": "UART baud error (UBRR, BRR), timer prescalers, PWM resolution, ADC LSB/ENOB and RC delays.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://ohmforgemcutiming.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "UART baud error (UBRR, BRR), timer prescalers, PWM resolution, ADC LSB/ENOB and RC delays.", "description": "Five firmware calculations with exact integer arithmetic: the UART divider (AVR UBRR normal and double speed, STM32 BRR with 16× or 8× oversampling, or any divider) with the real baud rate and error for your clock, a timer solver that finds prescaler and compare value for a target frequency or period on 8-, 16- or 32-bit timers, PWM frequency against resolution for fast and phase-correct PWM, ADC LSB size, ideal SNR and ENOB from SINAD, and RC reset or debounce times to a logic threshold.\n\nMethodology:\n- UART: AVR UBRR = round(fOSC/(16·baud) − 1) (U2X = 1: /8), real baud = fOSC/(16·(UBRR + 1)); STM32 USARTDIV = round(fCK/baud) with 16× oversampling and round(2·fCK/baud) with 8× oversampling, where BRR keeps USARTDIV[15:4] and BRR[2:0] = USARTDIV[3:0] >> 1 (USARTDIV ≥ 16); generic divider D = round(f/(N·baud)·2^F)/2^F. Error = real/wanted − 1.\n- Timer: f = fCLK/(P·N) with prescaler P and N counts per period (compare/auto-reload value N − 1). For each prescaler N = round(fCLK/(P·f)) must fit the timer (1 … 2^bits). \"Any 1 … 65536\" searches every prescaler and keeps the 10 best by error, then by most counts (finest resolution).\n- PWM: fast (single-slope) PWM f = fCLK/(P·(TOP + 1)); phase-correct (dual-slope) PWM f = fCLK/(2·P·TOP). In both modes the compare value runs 0 … TOP, so the resolution is log2(TOP + 1) bits.\n- ADC: LSB = Vref/2^N (the convention of most datasheets: code = floor(Vin·2^N/Vref)), quantisation noise LSB/√12, ideal SNR = 6.02·N + 1.76 dB for a full-scale sine, ENOB = (SINAD − 1.76)/6.02.\n- RC: the capacitor charges through R from 0 V: t = −RC·ln(1 − Vth/V) to the high threshold; discharging from V: t = −RC·ln(Vth/V) to the low threshold; settling to 1 % takes RC·ln 100 ≈ 4.6 RC.\n\nRegister names and formulas follow the cited families; other microcontrollers differ (extra prescaler stages, fractional dividers, clock trees). Check the reference manual of your exact part. The RC result assumes ideal parts and a high-impedance input; real thresholds vary with supply and temperature.", "tags": [ "apps" ], "x-mcp-tool": "ohmforge_mcu_timing", "x-owner-app": "ohmforge", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OhmforgeMcuTimingInput" }, "examples": { "example1": { "summary": "ATmega328P at 16 MHz: 115200 baud", "value": { "mode": "uart", "clockMHz": 16, "baud": 115200, "uartMode": "avr", "maxErrorPercent": 2 } }, "example2": { "summary": "STM32 at 8 MHz: 9600 baud with 8× oversampling (RM0360 example)", "value": { "mode": "uart", "clockMHz": 8, "baud": 9600, "uartMode": "stm32-8", "maxErrorPercent": 2 } }, "example3": { "summary": "AVR Timer1: 1 kHz interrupt from 16 MHz", "value": { "mode": "timer", "clockMHz": 16, "target": 1000, "targetKind": "frequency", "bits": "16", "prescalers": "avr-t0-t1" } }, "example4": { "summary": "STM32 timer: 1 Hz from 72 MHz", "value": { "mode": "timer", "clockMHz": 72, "target": 1, "targetKind": "frequency", "bits": "16", "prescalers": "stm32" } }, "example5": { "summary": "Arduino pin PWM: 490 Hz phase-correct, 8 bit", "value": { "mode": "pwm", "clockMHz": 16, "target": 490, "bits": "8", "prescalers": "avr-t0-t1", "pwmMode": "phase-correct" } }, "example6": { "summary": "12-bit ADC at 3.3 V with 70 dB SINAD", "value": { "mode": "adc", "adcBits": 12, "vref": 3.3, "vin": 1.65, "sinadDb": 70 } }, "example7": { "summary": "Reset RC: 10 kΩ and 100 nF into a 5 V Schmitt input", "value": { "mode": "rc", "r": "10k", "c": "100n", "supply": 5, "highThreshold": 3, "lowThreshold": 1.5, "targetTime": "20m" } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OhmforgeMcuTimingResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "OhmforgeMcuTimingInput": { "type": "object", "additionalProperties": false, "properties": { "mode": { "title": "Calculation", "type": "string", "enum": [ "uart", "timer", "pwm", "adc", "rc" ], "default": "uart" }, "clockMHz": { "title": "Clock (peripheral or timer clock)", "type": "number", "minimum": 0.000001, "maximum": 10000, "default": 16, "x-unit": "MHz" }, "baud": { "title": "Baud rate", "type": "number", "minimum": 1, "maximum": 100000000, "default": 115200, "x-unit": "bit/s" }, "uartMode": { "title": "Baud-rate generator", "type": "string", "enum": [ "avr", "avr-u2x", "stm32-16", "stm32-8", "generic" ], "default": "avr" }, "oversampling": { "title": "Oversampling (generic)", "description": "Clock cycles per bit of a generic UART, e.g. 16 for a 16550.", "type": "integer", "minimum": 1, "maximum": 1024, "default": 16 }, "fractionBits": { "title": "Fractional divider bits (generic)", "description": "0 = integer divider; 4 = divider in 1/16 steps.", "type": "integer", "minimum": 0, "maximum": 8, "default": 0 }, "maxErrorPercent": { "title": "Accepted baud error", "description": "±2 % is the usual design limit when both ends have their own error.", "type": "number", "minimum": 0.01, "maximum": 10, "default": 2, "x-unit": "%" }, "target": { "title": "Target frequency (timer, PWM) or period", "description": "Hz, or seconds when \"Target is\" is set to period.", "type": "number", "minimum": 1e-12, "maximum": 10000000000, "default": 1000 }, "targetKind": { "title": "Target is", "type": "string", "enum": [ "frequency", "period" ], "default": "frequency" }, "bits": { "title": "Timer width", "type": "string", "enum": [ "8", "16", "32" ], "default": "16" }, "prescalers": { "title": "Prescaler options", "type": "string", "enum": [ "avr-t0-t1", "avr-t2", "pic-t0", "stm32", "custom" ], "default": "avr-t0-t1" }, "customPrescalers": { "title": "My prescalers", "description": "For \"My own list\": whole numbers separated by commas.", "type": "string", "maxLength": 300, "default": "1, 8, 64, 256, 1024" }, "pwmMode": { "title": "PWM mode", "type": "string", "enum": [ "fast", "phase-correct" ], "default": "fast" }, "adcBits": { "title": "ADC resolution", "type": "integer", "minimum": 1, "maximum": 32, "default": 10, "x-unit": "bit" }, "vref": { "title": "Reference voltage", "type": "number", "minimum": 0.000001, "maximum": 10000, "default": 5, "x-unit": "V" }, "vin": { "title": "Input voltage to convert (optional)", "type": "number", "minimum": -10000, "maximum": 10000, "x-unit": "V" }, "sinadDb": { "title": "SINAD or SNR from the datasheet (optional)", "type": "number", "minimum": 0, "maximum": 300, "x-unit": "dB" }, "r": { "title": "Resistor R", "description": "Engineering notation: 10k, 4k7, 1M.", "type": "string", "maxLength": 32, "default": "10k" }, "c": { "title": "Capacitor C", "description": "100n = 100 nF, 1u = 1 µF.", "type": "string", "maxLength": 32, "default": "100n" }, "supply": { "title": "Supply voltage", "type": "number", "minimum": 0.000001, "maximum": 10000, "default": 5, "x-unit": "V" }, "highThreshold": { "title": "High input threshold", "description": "Voltage at which the input reads 1 (Schmitt trigger VT+, reset threshold).", "type": "number", "minimum": 0.000001, "maximum": 10000, "default": 3, "x-unit": "V" }, "lowThreshold": { "title": "Low input threshold (optional)", "description": "Voltage at which the input reads 0 again (VT−).", "type": "number", "minimum": 0.000001, "maximum": 10000, "default": 1.5, "x-unit": "V" }, "targetTime": { "title": "Delay you want (optional)", "description": "For example 20m = 20 ms: the capacitor for it is computed with your R.", "type": "string", "maxLength": 32, "default": "" } }, "required": [] }, "OhmforgeMcuTimingResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "required": [ "mode", "uart", "timer", "pwm", "adc", "rc" ], "additionalProperties": false, "properties": { "mode": { "type": "string", "enum": [ "uart", "timer", "pwm", "adc", "rc" ] }, "uart": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "clockHz": { "type": "number" }, "mode": { "type": "string" }, "registerName": { "type": "string" }, "oversampling": { "type": "integer" }, "fractionBits": { "type": "integer" }, "maxErrorPercent": { "type": "number" }, "setting": { "type": "object", "additionalProperties": false, "properties": { "baud": { "type": "number" }, "register": { "type": [ "integer", "null" ] }, "divider": { "type": [ "number", "null" ] }, "actualBaud": { "type": [ "number", "null" ] }, "errorPercent": { "type": [ "number", "null" ] }, "ok": { "type": "boolean" }, "problem": { "type": [ "string", "null" ] } } }, "alternative": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "baud": { "type": "number" }, "register": { "type": [ "integer", "null" ] }, "divider": { "type": [ "number", "null" ] }, "actualBaud": { "type": [ "number", "null" ] }, "errorPercent": { "type": [ "number", "null" ] }, "ok": { "type": "boolean" }, "problem": { "type": [ "string", "null" ] } }, "description": "Same baud rate with the other oversampling of the same family (AVR U2X, STM32 OVER8)." }, "table": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "baud": { "type": "number" }, "register": { "type": [ "integer", "null" ] }, "divider": { "type": [ "number", "null" ] }, "actualBaud": { "type": [ "number", "null" ] }, "errorPercent": { "type": [ "number", "null" ] }, "ok": { "type": "boolean" }, "problem": { "type": [ "string", "null" ] } } } } } }, "timer": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "clockHz": { "type": "number" }, "targetHz": { "type": "number" }, "bits": { "type": "integer" }, "prescalerSet": { "type": "string" }, "exact": { "type": "boolean" }, "best": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "prescaler": { "type": "integer" }, "counts": { "type": [ "integer", "null" ] }, "top": { "type": [ "integer", "null" ] }, "actualHz": { "type": [ "number", "null" ] }, "actualPeriodS": { "type": [ "number", "null" ] }, "errorPercent": { "type": [ "number", "null" ] }, "fits": { "type": "boolean" }, "overflowHz": { "type": "number" } } }, "rows": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "prescaler": { "type": "integer" }, "counts": { "type": [ "integer", "null" ] }, "top": { "type": [ "integer", "null" ] }, "actualHz": { "type": [ "number", "null" ] }, "actualPeriodS": { "type": [ "number", "null" ] }, "errorPercent": { "type": [ "number", "null" ] }, "fits": { "type": "boolean" }, "overflowHz": { "type": "number" } } } } } }, "pwm": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "clockHz": { "type": "number" }, "targetHz": { "type": "number" }, "bits": { "type": "integer" }, "mode": { "type": "string" }, "maxResolutionBits": { "type": "number" }, "best": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "prescaler": { "type": "integer" }, "top": { "type": [ "integer", "null" ] }, "steps": { "type": [ "integer", "null" ] }, "resolutionBits": { "type": [ "number", "null" ] }, "actualHz": { "type": [ "number", "null" ] }, "errorPercent": { "type": [ "number", "null" ] }, "fits": { "type": "boolean" } } }, "rows": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "prescaler": { "type": "integer" }, "top": { "type": [ "integer", "null" ] }, "steps": { "type": [ "integer", "null" ] }, "resolutionBits": { "type": [ "number", "null" ] }, "actualHz": { "type": [ "number", "null" ] }, "errorPercent": { "type": [ "number", "null" ] }, "fits": { "type": "boolean" } } } }, "fixed": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "resolutionBits": { "type": "integer" }, "prescaler": { "type": "integer" }, "frequencyHz": { "type": "number" } } } } } }, "adc": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "bits": { "type": "integer" }, "vref": { "type": "number" }, "codes": { "type": "number" }, "lsbV": { "type": "number" }, "fullScaleV": { "type": "number" }, "quantNoiseRmsV": { "type": "number" }, "idealSnrDb": { "type": "number" }, "code": { "type": [ "integer", "null" ] }, "codeVoltageV": { "type": [ "number", "null" ] }, "sinadDb": { "type": [ "number", "null" ] }, "enob": { "type": [ "number", "null" ] }, "effectiveLsbV": { "type": [ "number", "null" ] } } }, "rc": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "r": { "type": "number" }, "c": { "type": "number" }, "tauS": { "type": "number" }, "riseTimeS": { "type": "number" }, "fallTimeS": { "type": [ "number", "null" ] }, "settle1PercentS": { "type": "number" }, "capacitorForTargetF": { "type": [ "number", "null" ] }, "highFraction": { "type": "number" }, "lowFraction": { "type": [ "number", "null" ] } } } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }