Metadata-Version: 2.4
Name: elektro-cli
Version: 0.7.2
Summary: Terminal tabanlı Elektrik-Elektronik Mühendisliği aracı
Author-email: Ahmet Enes KAYMAK <kaymakahmetenes@gmail.com>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/0anes0/elektro
Project-URL: Issues, https://github.com/0anes0/elektro/issues
Keywords: electronics,engineering,cli,terminal,rf,circuit,datasheet
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13.0
Requires-Dist: requests>=2.28
Requires-Dist: beautifulsoup4>=4.11
Requires-Dist: textual>=0.47
Provides-Extra: plot
Requires-Dist: matplotlib>=3.5; extra == "plot"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

<div align="center">
  <h1>⚡ ELEKTRO</h1>
  <p><i>A terminal toolkit for electrical & electronics engineering</i></p>

  **English** · [Türkçe](https://github.com/0anes0/elektro/blob/main/README.tr.md)

  ![Python](https://img.shields.io/badge/python-3.9+-blue.svg)
  ![License](https://img.shields.io/badge/license-GPLv3-green.svg)
  ![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS-lightgrey.svg)
  ![Languages](https://img.shields.io/badge/lang-EN%20%7C%20TR%20%7C%20DE%20%7C%20RU-orange.svg)
  [![test](https://github.com/0anes0/elektro/actions/workflows/test.yml/badge.svg)](https://github.com/0anes0/elektro/actions/workflows/test.yml)
</div>

---

**Elektro** handles everyday electronics calculations from the terminal — Ohm's law, resistor
color codes, filter design, RF link budgets, 555 timers and more — and downloads component
datasheets with a single command.

All values accept engineering notation: `4k7`, `100n`, `2.2u`, `10M`, `1meg`, `1R5`, `100nF`, `1kΩ`

The interface is available in **English, Turkish, German and Russian**.

## 🛠️ Installation

```bash
curl -fsSL https://raw.githubusercontent.com/0anes0/elektro/main/install.sh | bash
```

The script creates an isolated virtual environment in `~/.local/share/elektro` and links the
`elektro` command into `~/.local/bin`. It does not touch your system Python and does not need
pipx. If you installed an older version with pipx, it removes it for you.

Requirement: **Python 3.9+** (on Debian/Ubuntu also `python3-venv`).

<details>
<summary>Install from the repo, update, uninstall</summary>

```bash
git clone https://github.com/0anes0/elektro.git
cd elektro
./install.sh                 # install
elektro update               # update to the latest version on GitHub
./install.sh --uninstall     # uninstall
```

Shell completion (bash/zsh/fish): `elektro --install-completion`
</details>

## 🌍 Language

By default elektro follows your system language (`LANG`), falling back to English.

```bash
elektro language             # list languages
elektro language de          # save German as the default
elektro --lang ru ohm -v 5 -r 1k   # one-off
ELEKTRO_LANG=tr elektro      # via environment variable
```

Priority: `--lang` → `ELEKTRO_LANG` → saved setting (`~/.config/elektro/config.json`) → system language → English.

## 🚀 Usage

Run `elektro` for the command menu, `elektro COMMAND --help` for details,
`elektro helpall` or `man elektro` for the full manual.

Every command accepts `--json` for machine-readable output:
`elektro ohm -v 12 -r 1k --json`

### Report output

Get results as tables for homework, lab reports or notes:

```bash
elektro ohm -v 12 -r 1k --md                 # Markdown table
elektro filter rc --r 1k --c 100n --latex    # LaTeX tabular
elektro cable -i 16 -l 25 --report lab.md    # append to lab.md (.tex → LaTeX)
elektro motor -p 7.5k --rpm 1450 --copy      # copy the output to the clipboard
```

With `--report` the normal output is still shown in the terminal; each command is appended
together with its command line. Graphs saved with `--plot` are embedded in Markdown reports.

### Terminal user interface (TUI)

```bash
elektro tui
```

Pick a command in the tree on the left (or search with `Ctrl+F`); its options open as a form and
the command line is built as you type. `Enter` / `Ctrl+R` runs it and the colored result appears
in the panel below. You can also type any `elektro` command into the command line directly.

| Key | Action |
|---|---|
| `F2` / `F3` / `F4` | Calculations / Circuit / History tab |
| `Ctrl+R` | Run |
| `Ctrl+F` | Search commands |
| `Ctrl+L` | Clear the output |
| `Ctrl+Q` | Quit |

In **History**, `Enter` on a row loads that command again.

### Circuit editor and simulator

`elektro tui circuit.json` or `F3` in the interface: draw a schematic with the keyboard, simulate it
and see the result in a graph. The simulator is elektro's own solver (nodal analysis, nothing
extra to install).

```
     A   B   C   D   E   F
  1  ·   ·   ·   ·   ·   ·
          5V        454.5mV
  2  ·   ●─[R1 10k]──●   ·
         +           │
  3  [V1 5V]     [R2 1k]
         │           │
  4  ·   ●───────────●   ·
       [GND]
```

| Key | Action |
|---|---|
| `r` `c` `l` `v` `i` `g` | place a resistor, capacitor, inductor, voltage/current source, ground |
| `d` `q` `f` `u` | place a diode, BJT, MOSFET, op-amp |
| `n` | net label (e.g. `VCC`, `OUT`): points with the same name are connected, probe as `V(OUT)` |
| `Ctrl+E` | example library: 93 circuits in folders, with a short explanation for students |
| `w` | wire: move the cursor, `Enter` sets a corner, `Esc` ends |
| `e` / `Enter` | change the value (`4k7`, `100n`; sources: `SINE(0 1 1k)`, `PULSE(0 5 0 1u 1u 0.5m 1m)`, `AC 1`) |
| `Ctrl+R` · `m` · `x` · `Ctrl+Z` | rotate · move · delete · undo |
| `p` | probe: voltage `V(C3)` on a point, current `I(R1)` on a component |
| `a` … `a` | current between two nodes `I(C1,C10)` |
| `o` … `o` | equivalent resistance between two points `R(A1,D1)` (works for resistor-only circuits) |
| `P` | type a probe: `V(C3,E7)`, `P(R1)`, transistor pin `I(Q1.B)` … |
| `s` | analysis: `.tran 10m`, `.ac dec 100 10 100k`, `.dc V1 0 5 0.1` (command line + form) |
| `F5` | solve; afterwards every change is solved again automatically |
| `F6` · `Tab` | plot size · go to the plot (`←`/`→` cursor, `m` magnitude/phase) |
| `Ctrl+S` · `Ctrl+O` · `Ctrl+N` | save · open · new |

For semiconductors the value is a model name (change it with `e`), optionally followed by parameters:

| Part | Models | Example |
|---|---|---|
| Diode | 1N4148, 1N4007, 1N5819, LED, LED-GREEN, LED-BLUE, LED-WHITE, BZX3V3, BZX5V1, BZX12 | `1N4148`, `IS=1e-14 N=1.8` |
| BJT | 2N2222, 2N3904, BC547 (NPN) · 2N3906, BC557 (PNP) | `2N2222 BF=150` |
| MOSFET | 2N7000, IRFZ44N (N) · BS250, IRF9540 (P) | `NMOS VTO=2 KP=0.5` |
| Op-amp | ideal, LM358, LM741, TL072 + output limit | `TL072 ±15`, `LM358 0..5` |

Nonlinear parts are solved with Newton-Raphson (diode: Shockley + breakdown, BJT: Ebers-Moll +
Early effect, MOSFET: level 1, op-amp: single pole with GBW + rail limit). Junction capacitances
are not modelled; results are meant for preliminary design.

Nodes are named like spreadsheet cells (the address of their top-left point: `B2`, `E2`). The plot
shows the probes, or all node voltages when there are none. The same file can be solved from the
command line:

**Example library.** Like Falstad's circuit simulator, a ready-made library of 93 circuits sorted
into folders: basics (Ohm, Kirchhoff, Thevenin, RC/RL/LC transients), AC circuits and resonance,
passive filters, diodes (rectifiers, clippers, clampers, voltage multipliers, zener, diode logic),
BJTs, MOSFETs (switches, amplifiers, CMOS inverter), op-amps (amplifiers, comparators and
nonlinear circuits, active filters), oscillators (relaxation, function generator, Wien bridge,
phase shift, ring) and power supplies (buck, boost, buck-boost, regulators, charge pump). Every
circuit opens with its probes and analysis ready and comes with a short explanation in four
languages, so students can open it, run it and change values to see what happens.

SPICE netlists work too. Opening a `.cir` / `.sp` / `.net` file places the parts on the grid and
connects them with net labels; unsupported lines are skipped with a warning.

```bash
elektro examples                               # the example library as a folder tree
elektro examples rc_lowpass                    # save it as rc_lowpass.json
elektro tui circuit.cir                        # import a SPICE netlist into the editor
elektro sim circuit.cir                        # solve a netlist directly
elektro sim circuit.json                       # DC operating point + the analysis in the file
elektro sim circuit.json -p "V(E2)" -p "I(B2,E2)"
elektro sim rc.json -a ".tran 5m" --plot rc.svg --csv rc.csv
elektro sim filter.json -a ".ac dec 50 10 1meg" --plot bode.svg
elektro sim circuit.json --spice > circuit.cir   # SPICE netlist
```

### Interactive mode, variables, history

```bash
elektro shell                        # type commands without "elektro"; Tab completes, ↑ recalls
elektro set vin 12                   # save a value …
elektro ohm -v @vin -r 1k            # … and use it as @vin in any command
elektro set rload 4k7 --local        # per project (./.elektro.json)
elektro calc "vin / 2"               # variables also work by name in calc
elektro vars                         # list variables
elektro history                      # previous calculations
elektro history --run 3              # run one again
```

### Basics

```bash
elektro ohm -v 12 -r 1k              # any two of V, I, R, P
elektro ohm                          # interactive wizard

elektro resistor bn bk rd gd         # color code → 1 kΩ ±5%  (3-6 bands)
elektro resistor yellow violet black brown brown
elektro resistor encode 4k7          # value → color code
elektro resistor smd 01C             # SMD code (103, 4R7, 1002, EIA-96)
elektro resistor table               # color table

elektro 555 astable --r1 1k --r2 10k --c 10u
elektro 555 astable -f 1k -d 60 --c 10n      # design R1/R2 from frequency
elektro 555 mono --t 5 --c 100u

elektro logic convert 0xFF           # decimal/hex/binary/octal
elektro logic convert --bits 8 -- -5 # two's complement
elektro logic truth xor
elektro logic expr "A & B | ~C"      # truth table of a boolean expression
elektro logic simplify "A&B | A&~B"  # minimal SOP + Karnaugh map
elektro logic simplify -m 1,3,7,11,15 -d 0,2,5

elektro opamp noninv --gain 11       # standard Rf/Rg pairs
elektro opamp inv --rf 47k --rin 4k7 --vin 0.5 --gbw 1M
elektro opamp diff --gain 5

elektro switch bjt --ic 500m -v 3.3  # base resistor for an NPN switch
elektro switch mosfet -v 10 --qg 40n -f 100k   # gate drive and losses
elektro charge --r 10k --c 100u --v 5 --to 3.3 # RC charge time + curve
```

Resistor colors can be given as IEC codes (`bk bn rd og ye gn bu vt gy wh gd sr`) or as names in
any of the four languages (`brown`, `kahverengi`, `braun`, `коричневый`).

### Passive components

```bash
elektro series 1k 2k2 470
elektro parallel 10u 22u --cap
elektro divider --vin 12 --r1 10k --r2 4k7
elektro divider --vin 5 --vout 3.3           # best E24 R1/R2 pairs
elektro led --vs 12 --vf 3.1 -i 15m -n 3     # LED resistor + power rating
elektro eseries 4k8                          # nearest standard values (E3-E192)
elektro cap 104                              # capacitor code ↔ value
elektro coil --l 1u --d 10                   # air-core coil turns (Wheeler)
elektro crystal --cl 12p                     # crystal load capacitors
```

### Power & wiring

```bash
elektro regulator lm317 --vout 5             # R2 for an adjustable regulator
elektro regulator 7805 --vin 12 -i 500m      # dissipation of a linear regulator
elektro battery 2000 -i 15m                  # battery life
elektro battery 1200 --active 45m --active-time 2 --sleep 20u --sleep-time 58
elektro thermal -p 5 --rth-jc 3 --ta 50      # required heatsink
elektro wire --awg 22 -l 3 -i 2              # AWG ↔ mm², voltage drop
elektro trace -i 3                           # PCB trace width (IPC-2221)
elektro rectifier --vac 12 -i 1 --ripple 1   # bridge rectifier + reservoir capacitor
elektro acpower --v 400 --p 15k --pf 0.82 --phases 3 --target-pf 0.95
elektro stardelta delta 10 20 30             # Δ → Y conversion
```

### Installation & machines

```bash
elektro cable -i 16 -l 25                    # cable size: current capacity + voltage drop
elektro cable -p 9k --phases 3 --pf 0.85 -l 40 --method C
elektro cable -i 120 --phases 3 -l 80 --material al --insulation xlpe --group 3
elektro breaker -i 14 --iz 21 --curve B --mm2 2.5 -l 30   # MCB selection, Zs, max. length
elektro breaker -i 40 --iz 50 --type fuse    # gG fuse
elektro shortcircuit --kva 630 --mm2 95 -l 50 --time 0.4  # Ik3, ip, Ik1, breaking capacity
elektro transformer --v1 230 --v2 12 --va 50 # ratio, currents, core area, turns, wire size
elektro motor -p 7.5k --rpm 1450             # current, torque, slip, starting current (Y-Δ)
```

Cable capacities come from the IEC 60364-5-52 tables (installation methods A1, B1, C, D, with
temperature and grouping correction). Results are for preliminary sizing; check them against
your local regulations.

### Filters

```bash
elektro filter rc --r 1k --c 100n            # fc + frequency response (gain/phase)
elektro filter rc --fc 1k --c 10n            # give two values, get the third
elektro filter rc --r 10k --fc 50 --high
elektro filter rl --r 1k --l 10m
elektro filter lc --f 433.92M --c 10p
elektro filter rlc --r 10 --l 1m --c 100n
elektro filter notch --r 1k --l 1.013 --c 10u  # 50 Hz
elektro filter rc --r 1k --c 100n --plot bode.svg   # save a Bode plot
elektro charge --r 10k --c 100u --v 5 --plot charge.svg
```

### Signal

```bash
elektro wave sine --rms 230                  # peak, average, RMS, crest/form factor
elektro wave pwm --vp 12 -d 25 -r 10         # DC and RMS of a PWM signal, power in a load
elektro wave square --vpp 5 --offset 2.5 --plot square.svg
elektro fft scope.csv                        # fundamental, harmonics, THD, THD+N
elektro fft adc.txt --rate 48k --window flattop --plot spectrum.svg
```

`fft` reads oscilloscope CSVs (Rigol, Siglent, Tektronix), `;`-separated files with decimal
commas and single-column raw data. The sample rate comes from the time column or the file
header; otherwise give `--rate`.

Graphs are written as SVG without any extra dependency. For `.png` / `.pdf` install matplotlib
into elektro's environment: `~/.local/share/elektro/venv/bin/pip install matplotlib`.

### RF

A plain number is **MHz** for frequency and **km** for distance (`2.4G` and `800m` also work).

```bash
elektro rf fspl -f 868 -d 5
elektro rf link -f 868 -d 10 --tx 14 --sens -137   # link margin and max. range
elektro rf wave -f 433.92                          # wavelength, antenna lengths
elektro rf convert 14 dbm w
elektro rf convert 1.5 vswr                        # |Γ|, return loss, mismatch loss
elektro rf lora --sf 9 -p 20                       # LoRa time on air, sensitivity
elektro rf fresnel -f 868 -d 10                    # Fresnel zone / antenna height
elektro rf microstrip --z0 50 --h 1.6 --er 4.4     # 50 Ω trace width
elektro rf coax lmr400 -f 2.4G -l 20m              # cable loss
```

### Embedded

```bash
elektro uart -c 16M -b 115200                # baud register and error (avr/stm32)
elektro pwm -c 72M -f 20k -m stm32 -d 25     # prescaler, ARR, compare value
elektro adc -b 12 --vref 3.3 --code 2048     # ADC code ↔ voltage
elektro i2c --cb 200p -s 400k                # I²C pull-up range
elektro crc "01 03 00 00 00 0A"              # CRC-8/16/32, Modbus, checksums
```

### Tools

```bash
elektro calc "12V / (4k7 + 1k)"              # calculator with engineering notation
elektro calc "par(1k, 2k2, 4k7)" -u Ω
elektro calc "230∠0 / (10 + zl(100m, 50))" -u A        # complex numbers and phasors
elektro calc "100 + zl(10m, 1k) || zc(1u, 1k)" -u Ω -f 1k  # impedance → series R + L/C
elektro unit 25 c                            # °C/°F/K, mil/mm, dB, AWG …
elektro pinout                               # parts with a known pinout
elektro pinout ne555                         # IC / transistor pinout (offline)
```

In `calc`, `j` is the imaginary unit (`3+4j`, `3+j4`), `10∠30` is polar form (degrees) and `||`
is the parallel combination. Functions: `re im abs arg conj polar zl zc`.

### Datasheet downloader

```bash
elektro datasheet lm358
elektro datasheet ams1117 --open       # download and open
elektro datasheet esp32 --list         # show candidates without downloading
elektro datasheet 2n2222 -o transistor.pdf
elektro datasheet --history            # previously downloaded (cached) datasheets
```

It checks manufacturer sites (TI, Espressif, onsemi, Diodes, Nexperia), then the LCSC/JLCPCB
parts database, and finally DuckDuckGo. The download is verified to be a real PDF; if no source
works, links for a manual search are printed. Downloads are cached in `~/.cache/elektro/`, so the
same part is available instantly next time.

## 🧪 Development

```bash
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest
```

Translations live in `elektro/i18n/` (`en.py` is the source). The tests check that every language
has every key with the same placeholders.

Releasing to PyPI (package name `elektro-cli`): add a *Trusted Publisher* for this repository on
PyPI (workflow `publish.yml`, environment `pypi`), then push a tag matching `__version__`:
`git tag v0.4.0 && git push origin v0.4.0`.

## 📄 License

[GPLv3](https://github.com/0anes0/elektro/blob/main/LICENSE) © Ahmet Enes KAYMAK
