Eren SOYLU

Reading a schematic when you are not an electrical engineer

2026-06-09T00:00:00Z

I write firmware. Every so often a board lands on my desk with a schematic, a half-finished bring-up doc, and a question: why doesn't the sensor respond? You do not need an EE degree to answer that. You need a method.

Start from the connector, not the corner

Schematics are drawn for the person who designed them, and their reading order is rarely useful to you. Do not start top-left. Start at the thing you are debugging and walk outwards:

Find the part in the schematic by its designator (U7, J3).
Find its power pins. Note the rail name — +3V3, VDDA, VBUS.
Find that rail's regulator. Note its enable pin and what drives it.
Only then follow the signal you actually care about.

Step 3 catches an embarrassing share of "dead peripheral" bugs. A rail with an enable pin tied to a GPIO is a rail that is off until your firmware turns it on.

Net names are the real index

Every wire belongs to a net, and nets have names. A good schematic uses the same net name everywhere the wire appears, including across sheets, and the off-sheet connector arrows tell you where to look next. If you can search the PDF, searching for I2C1_SDA is faster than tracing lines with a cursor.

Watch for the two ways this bites:

Buses. SPI2_MOSI may appear once as part of SPI2[0..3]. Expand the bus label before concluding the pin is unconnected.
Net aliases. Two names joined by a zero-ohm link or a solder bridge are the same net if the link is fitted. Check the BOM for "DNP" — do not populate. A DNP resistor is a wire that isn't there.

Pull-ups are configuration

On an I²C bus, the pull-up resistors are not decoration; they set the rise time and therefore the maximum usable clock. Two common failures:

No pull-ups at all because the designer assumed the MCU's internal ones. Internal pull-ups are typically tens of kΩ — far too weak for 400 kHz.
Pull-ups on two boards. Stack a carrier and a sensor board that each fit 4.7 kΩ and you get 2.35 kΩ, which some parts will not drive low enough.

If the bus works at 100 kHz and fails at 400 kHz, suspect the pull-ups before your driver.

Three measurements before you touch firmware

With a multimeter and five minutes:

Measure	Expect	If it's wrong
Each rail, board powered	Within a few % of nominal	Regulator not enabled, or shorted
Reset pin, idle	Held at the rail, not floating	Missing pull-up, or held by a debugger
SDA and SCL, bus idle	Both at the rail	Missing pull-ups, or a device holding the line

That last row is the one I forget most. A device stuck mid-transaction holds SDA low forever, and every subsequent transfer fails in a way that looks exactly like a driver bug. Nine clock pulses on SCL frees it — most vendor HALs have a bus_recover() for precisely this.

The habit worth building

Write down what you measured, where, and when, next to the schematic reference:

2026-06-08  rev B, s/n 004
  +3V3   3.29 V   ok
  VDDA   0.00 V   -> EN on U4 tied to PA8, firmware never drives it. Fixed.
  SDA    3.28 V   ok (R21/R22 fitted, 4k7)

Six months later that block tells you which board revision you were holding and what was already ruled out. It is the same reason I keep calibration constants in config rather than in code: a measurement without its context is just a number.

Graceful shutdown in Go is mostly about the order

2026-07-02T00:00:00Z

Most "graceful shutdown" examples stop at srv.Shutdown(ctx) and call it done. That drains in-flight HTTP requests, which is genuinely useful — and it is also the part least likely to lose anything. The data loss happens behind the handler, in whatever the request handed off to.

The shape of the problem

A typical service has layers that must stop in a specific order:

Stop accepting new work — the listener, and any queue consumer.
Finish work already accepted — in-flight handlers, in-flight jobs.
Flush anything buffered — metrics, batched writes, log shippers.
Close the connections those flushes needed.

Reverse any two of these and you get a class of bug that only shows up under deploy pressure: a batch writer closed before the handler that was about to use it, or a database pool closed while a job still holds a transaction.

Signal first, then unwind

func main() {
	ctx, stop := signal.NotifyContext(context.Background(),
		syscall.SIGINT, syscall.SIGTERM)
	defer stop()

	srv := &http.Server{Addr: ":8080", Handler: routes()}
	workers := worker.New(pool)

	go func() {
		if err := srv.ListenAndServe(); !errors.Is(err, http.ErrServerClosed) {
			log.Fatalf("listen: %v", err)
		}
	}()
	workers.Start()

	<-ctx.Done()
	log.Println("shutdown: draining")

	// Give the whole unwind one budget, not one per step.
	shutdownCtx, cancel := context.WithTimeout(context.Background(), 25*time.Second)
	defer cancel()

	// 1 + 2: stop accepting, finish in flight.
	if err := srv.Shutdown(shutdownCtx); err != nil {
		log.Printf("http drain: %v", err)
	}
	if err := workers.Drain(shutdownCtx); err != nil {
		log.Printf("worker drain: %v", err)
	}

	// 3: flush buffers that the above may have filled.
	if err := metrics.Flush(shutdownCtx); err != nil {
		log.Printf("metrics flush: %v", err)
	}

	// 4: only now is it safe to close the pool.
	pool.Close()
	log.Println("shutdown: complete")
}

Budget the whole unwind, not each step

The mistake I see most often is a fresh 30-second timeout at every stage. Your orchestrator does not care about your stages — Kubernetes sends SIGTERM, waits terminationGracePeriodSeconds, then sends SIGKILL. If the sum of your stage timeouts exceeds that grace period, the last stage never runs, and the last stage is usually the flush.

One context.WithTimeout shared across the unwind, set comfortably below the grace period, makes the arithmetic obvious:

terminationGracePeriodSeconds: 30   # must exceed the 25s budget above

Test it the boring way

You do not need a chaos framework. Start the service, put a slow request through it, send SIGTERM, and assert the request completed and the job landed:

curl -s localhost:8080/slow &
sleep 0.2
kill -TERM "$(pgrep -f myservice)"
wait

If that passes and your logs show the four stages in order, you have the property you actually wanted. Everything else is tuning.

Your PWM driver is lying to you

2026-08-14T00:00:00Z

I spent an evening convinced I had a bug in my servo easing code. The motion was smooth on the bench and jittery on the rig, and the difference tracked with nothing I could name. The code was fine. The clock was not.

The internal oscillator is nominal, not accurate

The PCA9685 datasheet gives its internal oscillator as 25 MHz. That number is a nominal figure with a tolerance, and individual parts land a few percent either side of it. The prescaler you write is computed against that assumed 25 MHz:

prescale = round(25_000_000 / (4096 * target_hz)) - 1

If the real oscillator runs at 26 MHz, every pulse you emit is about 4% shorter than you asked for. Ask for a 1500 µs neutral pulse and the servo sees roughly 1440 µs — which it reads as "rotate a bit". Across a chain of servos with slightly different parts, they disagree with each other too.

Measure the part in front of you

Put a scope or a logic analyser on one channel, ask for a known frequency, and measure what actually comes out. Then solve for the oscillator:

# Ask for 50 Hz, measure 52.1 Hz on the pin.
measured_hz = 52.1
requested_hz = 50.0
actual_osc = 25_000_000 * (measured_hz / requested_hz)  # ≈ 26.05 MHz

Store actual_osc per board and use it in the prescaler calculation instead of the constant. That is the whole fix:

def set_frequency(self, target_hz):
    prescale = round(self.osc_hz / (4096 * target_hz)) - 1
    self._write(MODE1, SLEEP)
    self._write(PRESCALE, max(3, min(255, prescale)))
    self._write(MODE1, RESTART)

Leave the knob in

The instinct is to hide the calibration behind a constant once you have measured one board. Don't. The next board will be different, and a osc_hz field in your config costs nothing:

[driver.pca9685]
address = 0x40
osc_hz = 26_050_000  # measured 2026-08-12, board rev C

A note with the date and the board revision turns a magic number into a measurement. Six months later, that comment is the difference between trusting the value and re-deriving it from scratch.

The general lesson is older than this chip: anything derived from a nominal oscillator, a nominal resistor, or a nominal supply voltage is an estimate. If your control loop cares, measure it once and write it down.