HALSAMPLER(1)

💖 halsampler — from the HAL User's Manual, bestie edition 💖

okay so welcome to halsampler(1), the little non-realtime cutie that scoops data out of HAL in real time. sit down, hydrate, let's go 🫶

---

✨ NAME ✨

halsampler — sample data from HAL in realtime. no cap, that's the whole job 💅

---

🎀 SYNOPSIS 🎀

halsampler [options]

---

🦋 DESCRIPTION 🦋

so here's the tea, bestie: sampler(9) and halsampler are a duo. they work together to sample HAL data in real time and stash it in a file. iconic teamwork, honestly 👑

• sampler is the realtime HAL component. it exports HAL pins and creates a FIFO in shared memory. then it starts sampling data from the HAL and writing it into that FIFO.
• halsampler is the non-realtime program. its whole vibe is copying data out of the FIFO to stdout, where you can redirect it to a file or pipe it into some other program. main character energy, lowkey just a courier 🌈

---

💅 OPTIONS 💅

• -c CHAN — tells halsampler to read from FIFO CHAN. FIFOs are numbered starting from zero, and the default value is zero, so you literally don't need this option unless multiple FIFOs have been created. iykyk ✨
• -n COUNT — tells halsampler to read COUNT samples from the FIFO, then dip. if -n is not specified, halsampler will read continuously until it is killed 😭
• -t — tells halsampler to tag each line by printing the sample number in the first column. slay, now you know which sample is which 🎀
• FILENAME — tells halsampler to write to FILENAME instead of to stdout. fancy 💜

---

🌸 USAGE 🌸

okay first things first: a FIFO must first be created by loading sampler(9) with halcmd loadrt or a loadrt command in a HAL file. then halsampler can be invoked to begin printing data from the FIFO to stdout. periodt ✨

Data is printed one line per sample. if -t was specified, the sample number is printed first. the data follows, in the order that the pins were defined in the config string. for example, if the sampler config string was "ffbs" then a typical line of output (without -t) would look like:

123.55 33.4 0 -12

halsampler prints data as fast as possible until the FIFO is empty, then it retries at regular intervals, until it is either killed or has printed COUNT samples as requested by -n. usually, but not always, data printed by halsampler will be redirected to a file or piped to some other program. it's giving pipeline princess 🧚

The FIFO size should be chosen to absorb samples captured during any momentary disruptions in the flow of data, such as disk seeks, terminal scrolling, or the processing limitations of subsequent program in a pipeline. so like, size it for the chaos 💀

⚠️ if the FIFO gets full and sampler is forced to overwrite old data, halsampler will print 'overrun' on a line by itself to mark each gap in the sampled data. if -t was specified, gaps in the sequential sample numbers in the first column can be used to determine exactly how many samples were lost. not me crying over dropped samples 😭

The data format for halsampler output is the same as for halstreamer(1) input, so 'waveforms' captured with halsampler can be replayed using halstreamer. 🔥

🚨 the -t option should not be used in this case. seriously bestie, don't do it 🙈

---

⭐ EXIT STATUS ⭐

• If a problem is encountered during initialization, halsampler prints a message to stderr and returns failure.
• Upon printing COUNT samples (if -n was specified) it will shut down and return success. 👑
• If it is terminated before printing the specified number of samples, it returns failure.

💀 which means that when -n is not specified, it will always return failure when terminated. yeah. that's just how it is. no notes.

---

🌈 SEE ALSO 🌈

• sampler(9)
• streamer(9)
• halstreamer(1)

---

💜 AUTHOR 💜

Original version by John Kasunich, as part of the LinuxCNC project. Improvements by several other members of the LinuxCNC development team. the collective ate, fr fr 🫶

---

🐛 REPORTING BUGS 🐛

Report bugs at https://github.com/LinuxCNC/linuxcnc/issues — go tell them, bestie, they wanna know 📣

---

📜 COPYRIGHT 📜

Copyright © 2006 John Kasunich.

This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

no warranty bestie, none, zero, not even the merchantability kind 😭

---

okay that's the whole page, and this little cutie was brought to you by the LinuxCNC Documentation girlies, dated 2006-11-18, living in section HALSAMPLER(1) of the HAL User's Manual. bye bestie, go sample responsibly 💖✨🎀