HISTOBINS(9)

🌸 HISTOBINS(9) — the HAL component page, bestie edition 🌸

okay so real talk, this page is for histobins, which is the histogram bins utility that goes with scripts/hal-histogram. it counts stuff into bins and hands you stats back. it's iconic, it's lowkey powerful, and it requires a floating-point thread so don't even try it without one. 💅

---

✨ NAME ✨

histobins — histogram bins utility for scripts/hal-histogram

like, it makes histogram bins. for that script. that's the whole vibe.

---

🌈 SYNOPSIS 🌈

Usage:

Read availablebins pin for the number of bins available.
Set the minvalue, binsize, and nbins pins.
  Ensure nbins <= availablebins
  For nbins = N, the bins are numbered: 0 ... N-1
Iterate:
  Set index pin to a bin number: 0 <= index < nbins.
  Read check pin and verify that check pin == index pin.
  Read outputs: binvalue, pextra, nextra pins.
       (binvalue is count for the indexed bin)
       (pextra   is count for all inputs > maxvalue)
       (nextra   is count for all bins   < minvalue)

If index is out of range (index < 0 or index > maxbinnumber)
then binvalue == -1.
The input-error pin is set when input rules are violated
and updates cease.
The reset pin may be used to restart.
The input used is selected based on pintype:
  pintype  inputpin
  -------  -----------
        0  input
        1  input-s32
        2  input-u32
        3  input-bit
Additional output statistics pins:
  input-min
  input-max
  nsamples
  variance
  mean
The method input pin selects an alternate variance calculation.

Maintainers note: hardcoded for MAXBINNUMBER==200

let me translate that into bestie-speak real quick, because it's giving "cryptic but correct": 🫶

• first you read the availablebins pin to find out how many bins you even have to work with.
• then you set the minvalue, binsize, and nbins pins. make sure nbins <= availablebins, bestie, we are not overflowing today.
• for nbins = N, the bins get numbered 0 ... N-1. yes, zero-indexed, we love that for us.
• now the loop:
  1. set the index pin to the bin number you want: 0 <= index < nbins.
  2. read the check pin and confirm check pin == index pin. this is your vibe check, literally.
  3. read your outputs: binvalue, pextra, nextra.
     • binvalue is the count for the indexed bin
     • pextra is the count for all inputs > maxvalue
     • nextra is the count for all bins < minvalue

⚠️ heads up queen: if index is out of range (index < 0 or index > maxbinnumber), then binvalue == -1. and if the input rules get violated, the input-error pin goes off and updates cease — everything just stops. use the reset pin to restart. 😭

which input gets used? it all depends on pintype, no cap:

• pintype 0 → input
• pintype 1 → input-s32
• pintype 2 → input-u32
• pintype 3 → input-bit

additional output statistics pins, because we don't gatekeep:

• input-min
• input-max
• nsamples
• variance
• mean

and the method input pin selects an alternate variance calculation. ✨

🧚 maintainers note: hardcoded for MAXBINNUMBER==200. that's just how it is, fr fr.

---

🎀 FUNCTIONS 🎀

• histobins.N — requires a floating-point thread. yes, it's demanding. it's the main character.

---

💅 PINS 💅

every single one, listed with love:

• histobins.N.pintype u32 in
• histobins.N.input float in
• histobins.N.input-s32 s32 in
• histobins.N.input-u32 u32 in
• histobins.N.input-bit bit in
• histobins.N.nbins u32 in (default: 20)
• histobins.N.binsize float in (default: 1)
• histobins.N.minvalue float in (default: 0)
• histobins.N.index s32 in
• histobins.N.check s32 out
• histobins.N.reset bit in
• histobins.N.method bit in
• histobins.N.input-error bit out
• histobins.N.binvalue float out
• histobins.N.pextra float out
• histobins.N.nextra float out
• histobins.N.input-min float out
• histobins.N.input-max float out
• histobins.N.nsamples u32 out
• histobins.N.variance float out
• histobins.N.mean float out
• histobins.N.availablebins s32 out (default: 200)

twenty-two pins, all accounted for, not one skipped. we ate. 👑

---

👑 AUTHOR 👑

Dewey Garrett

---

🦋 LICENSE 🦋

GPL

---

and that's the whole page bestie 💖 this one is from LinuxCNC Documentation, dated 2026-03-17 — go forth and histogram, you've got this. 🌸✨