TimeIt EDA

A scriptable graphical editor for creating precise digital timing diagrams for FPGA, ASIC and SoC documentation.

TimeIt combines an interactive waveform canvas with a built-in Tcl console. It is designed for digital hardware engineers who need to describe, review and communicate timing relationships involving clocks, inputs, outputs, delays, uncertainty, markers and annotations.

Why TimeIt?

Timing diagrams often need to express more than logical high and low levels. They may also need to show launch and capture clocks, input and output delays, timing uncertainty, setup and hold relationships, generated clocks and symbolic timing parameters.

TimeIt provides an EDA-oriented workflow for creating these diagrams:

• Model hardware timing concepts such as clocks, input signals, output signals, delays and timing windows.
• Build parametric diagrams using named timing variables and mathematical expressions.
• Combine graphical and scripted editing through an interactive canvas and Tcl console.
• Add timing markers and annotations for design reviews and interface specifications.
• Save diagrams as Tcl scripts that can be inspected, version-controlled and reused.
• Bootstrap SDC constraint files by generating partial set_input_delay / set_output_delay / set_multicycle_path statements from the diagram.
• Export to PNG, JPEG, SVG, PDF, EPS and PostScript.
• Run fully offline without network connections.
• Install without administrator rights by copying the source bundle.
• Use no third-party Python packages beyond Python and Tkinter/Tcl-Tk.

Note

TimeIt is intended for timing specification, documentation and visual reasoning. It does not replace HDL simulation or a static timing analysis engine.

Typical use cases

• Document FPGA, ASIC and SoC interface timing requirements.
• Explain launch/capture relationships during design reviews.
• Represent setup, hold, input-delay and output-delay requirements.
• Visually cross-check timing concepts and generate a first cut of the SDC I/O constraints.
• Produce scalable diagrams for datasheets, reports and presentations.
• Create reusable protocol illustrations for SPI, QSPI, I²C, JTAG or SWD.
• Explore the effect of changing a clock period or timing parameter across a complete diagram.

Quick start

Requirements

• Python 3.10 or later
• Tkinter / Tcl-Tk

Tkinter is normally bundled with Python. On some Linux distributions, it must be installed separately.

Install Tkinter on Linux

# Debian / Ubuntu
sudo apt install python3-tk

# Fedora
sudo dnf install python3-tkinter

# Arch Linux
sudo pacman -S tk

Clone and launch

Run these commands from the directory in which you want the TimeIt folder to be created:

git clone https://github.com/pcardaba/TimeIt.git
python3 -m TimeIt.main

On Windows, depending on your Python installation:

git clone https://github.com/pcardaba/TimeIt.git
py -m TimeIt.main

Important

Launch TimeIt from the directory containing the TimeIt folder, not from inside the package directory.

You can also download a stable source archive from the Releases page. Extract it, rename the extracted directory to TimeIt when necessary, open a terminal in its parent directory and run the same module command.

For detailed instructions, see the installation guide and launch guide.

First steps

After launching TimeIt:

1. Load one of the example Tcl scripts from the scripts/ directory.
2. Inspect the commands in the built-in Tcl console.
3. Modify a clock, signal or timing variable.
4. Use the canvas context menus to edit the diagram interactively.
5. Save the result as a Tcl script.
6. Export the complete canvas through File → Export Canvas….

Useful shortcuts:

• Ctrl + S — save the current diagram
• Ctrl + Z / Ctrl + Y — undo / redo the last diagram edit
• Shift + mouse wheel — zoom the waveform canvas

Parametric timing diagrams

TimeIt diagrams can use named variables instead of hard-coded numerical values. Variables may also contain expressions derived from other variables.

set_app_var -name timings.Tclk \
    -desc {Clock period} \
    -value {10}

set_app_var -name timings.Thalf \
    -desc {Half clock period} \
    -value {$Tclk/2.0}

set_app_var -name timings.tSU \
    -desc {Setup requirement} \
    -value {2.0}

set_app_var -name timings.tHO \
    -desc {Hold requirement} \
    -value {1.0}

create_clock -name clk \
    -topology source \
    -period {$Tclk} \
    -rise_at {0} \
    -fall_at {$Thalf} \
    -visible

create_output -name data_o \
    -specify external \
    -launch_clock clk \
    -data_edges {1P 2P 3P} \
    -rclk_outputdly_max {$tSU} \
    -rclk_outputdly_min {-$tHO} \
    -visible

Change Tclk, tSU or tHO, and all signals and markers that reference those variables are recalculated and redrawn.

Read more in Using timing variables.

Main capabilities

Area	Capabilities
Clocks	Source and generated (divided) clocks, clock gating, period, rise/fall positions, uncertainty and clock relationships
Signals	Input and output waveforms referenced to launch and capture clocks
Timing specification	Input delays, output delays, timing windows and symbolic expressions
Diagram editing	Create, copy, move, modify and remove signals interactively, with undo/redo
Measurements	Timing markers between waveform points
Annotations	Text and colour annotations attached to waveform segments
Analog (PWL) signals	Piece-wise linear waveforms (voltage, current, temperature…) read from text files, several per slot, with value markers
Layout	Canvas scaling, signal spacing, grid configuration and display settings
Automation	Built-in Tcl command interpreter, reusable Tcl scripts, and a session log that records every GUI action as its equivalent command
SDC generation	Partial constraint file (set_input_delay, set_output_delay, set_multicycle_path) derived from the diagram
VCD import	Waveform reproduction from HDL/gate-level simulation dumps, with min/max corner comparison
Persistence	Save and reload complete timing diagrams
Export	PNG, JPEG, SVG, PDF, EPS and PostScript

Examples

TimeIt includes reusable examples for several common digital interfaces:

Example	Script
I²C frame	I2C_Frame.tcl
I²C frame with pull-up behaviour	I2C_Frame_pulledup.tcl
JTAG timing	JTAG_Timing.tcl
QSPI program instruction	QSPI_program_inst.tcl
SPI mode 0	SPI_CPOL0_CPHA0.tcl
SPI mode 0 with timing markers	SPI_CPOL0_CPHA0.marked.tcl
SWD timing	SWD_Timing.tcl
Generated and gated clocks	gclk_example.tcl

I²C frame example	Interactive canvas and Tcl console

Exporting diagrams

Use File → Export Canvas… or the Tcl command:

# Vector output for technical documentation
export_canvas -file {diagram.svg}

# High-resolution raster output
export_canvas -file {diagram.png} -dpi 600 -background {#f0f0f0}

# Explicit output format
export_canvas -file {report/figure3} -format pdf

SVG and PDF preserve vector quality and are recommended for specifications and reports. See the export guide for all supported options.

Generating SDC constraints

The input and output signals of a diagram can be turned into a partial constraint file in SDC (Synopsys Design Constraints) format through File → Write SDC… or the Tcl command:

write_sdc -file {constraints.sdc}

The generated file contains set_input_delay / set_output_delay statements derived from the diagram delays (internally specified delays are converted to their external equivalents), plus set_multicycle_path statements whenever a signal's launch and capture clocks differ. The diagram timing variables are re-declared so the statements stay symbolic, and the diagram clocks are sketched as commented-out create_clock / create_generated_clock templates.

Important

The generated file is an aid to bootstrap the I/O constraining work, not a ready-to-use constraint deck: review every statement and rework it to match the real design. See Writing an SDC constraint file for the assumptions the file is built on.

Importing simulation waveforms

File → Import VCDs… reproduces the waveforms of a real HDL or gate-level simulation from VCD dump files. Two dumps are given — a best-case (min delays) and a worst-case (max delays) corner, or the same file twice — and TimeIt cross-checks them, detects clocks and derived clocks, proposes a role for every signal in a characterization dialog, and rebuilds the bundle as regular TimeIt clocks, inputs and outputs (min/max delay spreads become transition windows, clock shifts become uncertainties). See Importing VCD dump files.

Analog (PWL) signals

Supply voltages, currents, power or temperature can be shown next to the digital waveforms as PWL (piece-wise linear) signals, read from small two-column text files (time, value) with SI prefixes in SPICE style (10mV, 1.8V, 120mA). Several PWL signals can share one waveform slot, each with its own color, line style, vertical scale and offset, and value markers read the interpolated value at any point of a trace:

create_pwl -names {VDD IDD} -files {vdd.pwl idd.pwl} -height 120 -visible
set_attribute -signal {IDD} -name color -value red
create_value_marker -signal {VDD} -at 130

PWL signals are documentation signals: they take no part in the SDC generation. See PWL signals.

Documentation

The complete user guide is available in docs/.

Topic	Guide
Overview and concepts	Introduction
Installation	How to install TimeIt
Application launch and layout	How to launch TimeIt
Clock creation	Clock signals
Input and output signals	I/O signals
Timing measurements	Timing markers
Saving and loading	Save and load
Background grid	Grid
Canvas export	Exporting diagrams
Waveform annotations	Annotations
Copying signals	Copy a signal
Reordering signals	Move a signal
Deleting signals	Delete a signal
Editing signals	Modify a signal
Layout and display	Waveform layout
Built-in command help	Command help
Canvas scaling	Scale the canvas
Parametric diagrams	Timing variables
SDC constraint generation	Write SDC
VCD waveform import	Import VCDs
Analog (PWL) signals	PWL signals

For changes between versions, see the changelog and release notes.

Why Python?

TimeIt is intentionally implemented in Python using the standard library and Tkinter/Tcl-Tk.

This design makes the application:

• easy to inspect and audit;
• suitable for restricted engineering environments;
• deployable as source code without administrator rights;
• independent of external package repositories;
• easy to customise for project-specific workflows;
• fully local, with no network connection made by the application.

The goal is not to compete with a native application on raw rendering performance. The goal is to provide a transparent, portable and practical timing-diagram tool for hardware engineers.

Contributing

Bug reports, feature requests, documentation improvements, protocol examples and pull requests are welcome.

• Use GitHub Issues to report a bug or suggest a feature.
• Use Pull Requests to propose a change.
• Include a minimal Tcl script when reporting a diagram-generation problem.
• Screenshots and exported files are useful when reporting rendering issues.

Before submitting a change, please keep the application’s main deployment goals in mind: offline operation, source transparency and minimal dependencies.

Contact

For project-related questions:

timeit.oss+contact@gmail.com

License

TimeIt is distributed under the GNU General Public License version 3.

---

If TimeIt is useful to your work, consider giving the repository a star, sharing it with another digital hardware engineer, or contributing an example script.