pig2vcd(1)

💖 NAME 💖

pig2vd — bestie, it's a utility that converts pigpio notifications into VCD. yes the manpage really spells it pig2vd up there, I'm not doing a bit, that's just what it says 💅

---

✨ SYNOPSIS ✨

pig2vcd </dev/pigpioXX >file.VCD

it's giving "redirect in, redirect out, no vibes lost" 🎀

---

🦋 DESCRIPTION 🦋

okay so pig2vcd is a little utility that reads notifications on stdin and writes the output as a Value Change Dump (VCD) file on stdout. that's it. that's the whole job. and it eats. 🔥

you can then go look at that VCD file with GTKWave. 🌈

🌸 Notifications 🌸

a notification is 12 bytes long, and the binary format is literally this, no cap:

typedef struct
{
   uint16_t seqno;
   uint16_t flags;
   uint32_t tick;
   uint32_t level;
} gpioReport_t;

• seqno — starts at 0 every single time the handle gets opened, then just increments by one for each report. iconic behaviour, honestly.
• flags — two flags are defined here: PI_NTFY_FLAGS_WDOG and PI_NTFY_FLAGS_ALIVE.
  • if bit 5 is set (PI_NTFY_FLAGS_WDOG), then bits 0-4 of the flags indicate a gpio that has had a watchdog timeout 👀
  • if bit 6 is set (PI_NTFY_FLAGS_ALIVE), that means there's a keep alive signal on the pipe/socket, and it gets sent once a minute when there's no other notification activity. it's the "still here bestie 🫶" ping.
• tick — the number of microseconds since system boot. it wraps around after 1h12m. yes, it does the loop-de-loop. 🌀
• level — tells you the level of each gpio. if bit 1<<x is set, then gpio x is high. pig2vcd takes all these notifications and spits out a text format VCD. slay.

💜 VCD format 💜

the VCD starts with a header, and the header looks exactly like this:

$date 2013-05-31 18:49:36 $end
$version pig2vcd V1 $end
$timescale 1 us $end
$scope module top $end
$var wire 1 A 0 $end
$var wire 1 B 1 $end
$var wire 1 C 2 $end
$var wire 1 D 3 $end
$var wire 1 E 4 $end
$var wire 1 F 5 $end
$var wire 1 G 6 $end
$var wire 1 H 7 $end
$var wire 1 I 8 $end
$var wire 1 J 9 $end
$var wire 1 K 10 $end
$var wire 1 L 11 $end
$var wire 1 M 12 $end
$var wire 1 N 13 $end
$var wire 1 O 14 $end
$var wire 1 P 15 $end
$var wire 1 Q 16 $end
$var wire 1 R 17 $end
$var wire 1 S 18 $end
$var wire 1 T 19 $end
$var wire 1 U 20 $end
$var wire 1 V 21 $end
$var wire 1 W 22 $end
$var wire 1 X 23 $end
$var wire 1 Y 24 $end
$var wire 1 Z 25 $end
$var wire 1 a 26 $end
$var wire 1 b 27 $end
$var wire 1 c 28 $end
$var wire 1 d 29 $end
$var wire 1 e 30 $end
$var wire 1 f 31 $end
$upscope $end
$enddefinitions $end

so what's happening in there? the header defines the gpio identifiers and their name. every gpio identifier has to be unique — no twins allowed. pig2vcd just arbitrarily uses 'A' through 'Z' for gpios 0 through 25, and 'a' through 'f' for gpios 26 through 31. the corresponding names are 0 through 31. very "assigned seating at a birthday party" of it. 🎀

✨ pro move: you can literally edit the VCD file to give things a friendlier name. like, 8 could be changed to ENCODER_A if an encoder switch A is connected to gpio 8. do it, your future self will thank you. 🫶

after the header, pig2vcd takes notifications and outputs a timestamp followed by a list of one or more gpios that have changed state. the timestamp is a '#' followed by the microsecond tick. the state lines are the new state followed by the gpio identifier. obsessed.

#1058747
0H
0I
#1059012
1H
#1079777
1I
#1079782
0I
#1079852
1I
#1079857
0I
0H
#1165113
1H
#1165118
0H
#1165153
1H

---

🌈 SEE ALSO 🌈

• pigpiod(1)
• pigs(1)
• pigpio(3)
• pigpiod_if(3)
• pigpiod_if2(3)

go read those too, bestie, the whole friend group is iconic 💅

---

👑 AUTHOR 👑

joan@abyz.me.uk — the main character who wrote this 🫶

---

okay that's the whole page!! this one lives in the pigpio archive on Linux, dated 2012-2020, and the manpage goes by pig2vcd(1). mwah, go dump some values 💖✨🎀