radbeeper 0.4.2

A GQ GMC Geiger-Muller counter on the desk: find it, watch it, four time constants at once
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 Paul Richeson
// The GQ GMC protocol, and finding a counter that speaks it.
//
// Commands are ASCII <NAME>> and replies are a fixed number of raw bytes with
// no framing, so the only way to stay in step is to ask for exactly what you
// expect and time out rather than block.
use crate::serial::{OpenError, Serial};
use std::fs;
use std::time::Duration;

pub const BAUD_RATES: [u32; 2] = [115200, 57600];
pub const COUNT_MASK: u16 = 0x3FFF;
pub const DEFAULT_CPM_PER_USVH: f64 = 151.5;
pub const SPIR_CHUNK: usize = 2048;

/// How far the counter's clock is ahead of this machine's, and how far that
/// figure can be trusted. Negative `ahead` is behind.
#[derive(Clone, Copy, Debug)]
pub struct ClockOffset {
    pub ahead: f64,
    pub within: f64,
    /// What the counter's clock read, as seconds since the epoch in local time.
    pub theirs: f64,
}

pub struct Counter {
    port: Serial,
    pub version: String,
    pub serial_no: String,
    pub path: String,
    pub baud: u32,
}

/// No counter, with a reason a person can act on. The three ways this fails
/// have three different fixes, so they are three different messages.
pub struct NotFound {
    pub reason: String,
    pub detail: String,
    pub busy: bool,
}

/// The device nodes a counter could be behind, sorted.
///
/// `hotplug` watches this list rather than the port itself: opening a serial
/// port every few seconds to ask what is on it would fight the monitor for the
/// device the moment one was running, and rattle every other serial cable on
/// the machine besides. A node APPEARING is the event worth acting on.
pub fn candidate_ports() -> Vec<String> {
    let mut out = Vec::new();
    if let Ok(entries) = fs::read_dir("/dev") {
        let mut names: Vec<String> = entries
            .filter_map(|e| e.ok())
            .map(|e| e.file_name().to_string_lossy().into_owned())
            .filter(|n| n.starts_with("ttyUSB") || n.starts_with("ttyACM"))
            .collect();
        names.sort();
        out.extend(names.into_iter().map(|n| format!("/dev/{}", n)));
    }
    out
}

/// Whether the running kernel could bind a USB serial adapter at all.
///
/// Alpine's linux-virt ships none: no ch341, no usbserial. A counter plugged
/// into a VM running it can never appear, and dmesg is silent because nothing
/// ever claims the device.
fn usb_serial_driver_present() -> bool {
    if let Ok(mut d) = fs::read_dir("/sys/bus/usb-serial/drivers") {
        if d.next().is_some() {
            return true;
        }
    }
    false
}

impl Counter {
    fn ask(&self, cmd: &[u8], want: usize) -> Vec<u8> {
        self.port.flush_input();
        let _ = self.port.write_all(cmd);
        self.port
            .read_exact_or_timeout(want, Duration::from_millis(1000))
    }

    pub fn model(&self) -> String {
        model_of(&self.version)
    }

    pub fn cpm(&self) -> Option<u16> {
        let r = self.ask(b"<GETCPM>>", 2);
        (r.len() == 2).then(|| u16::from_be_bytes([r[0], r[1]]))
    }

    pub fn voltage(&self) -> Option<f64> {
        let r = self.ask(b"<GETVOLT>>", 1);
        (r.len() == 1).then(|| r[0] as f64 / 10.0)
    }

    /// One <GETDATETIME>> as (the counter's time, when it was asked, when it
    /// answered), all seconds since the epoch.
    fn clock_reading(&self) -> Option<(f64, f64, f64)> {
        let sent = radbeeper::clock::now();
        let r = self.ask(b"<GETDATETIME>>", 7);
        let got = radbeeper::clock::now();
        if r.len() != 7 {
            return None;
        }
        let theirs = radbeeper::clock::from_parts(
            2000 + r[0] as i32, r[1] as i32, r[2] as i32,
            r[3] as i32, r[4] as i32, r[5] as i32,
        )?;
        Some((theirs, sent, got))
    }

    /// The counter's clock against this machine's, timed to its tick.
    ///
    /// ONE READING IS ONLY GOOD TO A SECOND. The counter answers in whole
    /// seconds, so "15:31:54" is anywhere in that second and the difference
    /// from this machine's clock is uncertain by all of it -- 0.85 s out on
    /// the unit this was written against. So it asks again, back to back,
    /// until the second changes. The tick happened after the counter took
    /// the last old answer and before it sent the first new one, which pins
    /// it between two round trips: a few hundredths of a second at 115200.
    ///
    /// Falls back to the single reading, and says so in `within`, if the
    /// second never turns over -- a stopped clock is worth reporting too.
    pub fn clock_ahead(&self) -> Option<ClockOffset> {
        let (first, sent, got) = self.clock_reading()?;
        let fallback = ClockOffset {
            ahead: first - (sent + got) / 2.0 + 0.5,
            within: 0.5 + (got - sent) / 2.0,
            theirs: first,
        };
        let mut before = sent;
        let give_up = got + 2.5;
        while radbeeper::clock::now() < give_up {
            let (theirs, s, g) = match self.clock_reading() {
                Some(r) => r,
                None => return Some(fallback),
            };
            if theirs != first {
                let tick = (before + g) / 2.0;
                return Some(ClockOffset {
                    ahead: theirs - tick,
                    within: (g - before) / 2.0,
                    theirs,
                });
            }
            before = s;
        }
        Some(fallback)
    }

    /// Set the counter's clock to `when`, seconds since the epoch, read as
    /// local time. True if the counter acknowledged it.
    pub fn set_clock(&self, when: f64) -> bool {
        let parts = radbeeper::clock::format(when, "%y %m %d %H %M %S");
        let bytes: Vec<u8> = parts
            .split(' ')
            .filter_map(|p| p.parse::<u8>().ok())
            .collect();
        if bytes.len() != 6 {
            return false;
        }
        let mut cmd = b"<SETDATETIME".to_vec();
        cmd.extend_from_slice(&bytes);
        cmd.extend_from_slice(b">>");
        self.ask(&cmd, 1) == [0xAA]
    }

    /// How much history flash the model carries.
    pub fn flash_size(&self) -> usize {
        match self.model().as_str() {
            "GMC-320" | "GMC-500" | "GMC-600" => 0x100000,
            _ => 0x10000,
        }
    }

    /// `length` bytes of the history flash from `address`.
    ///
    /// The reply has no framing, so each chunk asks for exactly what it
    /// expects and stops short rather than falling out of step with the
    /// device -- a short read here is the end of what the counter will give,
    /// not something to retry into.
    pub fn read_history(&self, address: usize, length: usize) -> Vec<u8> {
        let mut out = Vec::with_capacity(length);
        while out.len() < length {
            let n = SPIR_CHUNK.min(length - out.len());
            let a = address + out.len();
            let mut cmd = b"<SPIR".to_vec();
            cmd.push(((a >> 16) & 0xFF) as u8);
            cmd.push(((a >> 8) & 0xFF) as u8);
            cmd.push((a & 0xFF) as u8);
            cmd.push(((n >> 8) & 0xFF) as u8);
            cmd.push((n & 0xFF) as u8);
            cmd.extend_from_slice(b">>");
            // A SHORT REPLY IS ASKED AGAIN BEFORE IT IS BELIEVED. The reply
            // has no framing, so a chunk that lost bytes on the link and the
            // real end of the flash look the same -- and taking the first for
            // the second cut a monitor's backfill off after its oldest 7 KiB,
            // so the newest hours, the ones it was reading for, were never
            // read. The port is drained between tries so a late remainder of
            // the last reply cannot be taken for the start of the next.
            let mut chunk = Vec::new();
            for attempt in 0..3 {
                if attempt > 0 {
                    std::thread::sleep(Duration::from_millis(300));
                }
                self.port.flush_input();
                let _ = self.port.write_all(&cmd);
                chunk = self
                    .port
                    .read_exact_or_timeout(n, Duration::from_millis(5000));
                if chunk.len() == n {
                    break;
                }
            }
            if chunk.is_empty() {
                break;
            }
            let short = chunk.len() < n;
            out.extend_from_slice(&chunk);
            if short {
                break;
            }
        }
        out
    }

    pub fn heartbeat(&self, on: bool) {
        self.port.flush_input();
        let _ = self
            .port
            .write_all(if on { b"<HEARTBEAT1>>" } else { b"<HEARTBEAT0>>" });
        if !on {
            // THE DEVICE MAY ALREADY HAVE QUEUED A SAMPLE. Turning the
            // stream off does not unsend the two bytes already on their way,
            // and the next thing to open this port asks <GETVER>> and could
            // read them as its answer. The Python has done this since the
            // beginning; this is parity with it. Costs a fifth of a second,
            // once, at the end of a session.
            std::thread::sleep(Duration::from_millis(200));
            self.port.flush_input();
        }
    }

    /// One counts-per-second sample, or None if the counter went quiet.
    ///
    /// The top two bits of the 16-bit value are status flags on current
    /// firmware, not count, which is why the mask is here and not optional.
    pub fn next_sample(&self, timeout: Duration) -> Option<u16> {
        let r = self.port.read_exact_or_timeout(2, timeout);
        (r.len() == 2).then(|| u16::from_be_bytes([r[0], r[1]]) & COUNT_MASK)
    }
}

fn identify(path: &str, baud: Option<u32>) -> Result<Option<Counter>, OpenError> {
    let rates: Vec<u32> = match baud {
        Some(b) => vec![b],
        None => BAUD_RATES.to_vec(),
    };
    for rate in rates {
        let port = match Serial::open(path, rate, Duration::from_millis(1000)) {
            Ok(p) => p,
            Err(OpenError::Busy) => return Err(OpenError::Busy),
            Err(_) => continue,
        };
        // A SESSION THAT WAS KILLED LEFT THE STREAM ON. `heartbeat(false)`
        // only runs on a clean exit; a SIGKILL, a pulled cable or a crash
        // leaves the counter sending two bytes a second into a port nobody
        // is reading, and flush-then-ask cannot beat that -- a sample lands
        // between the flush and the answer and every reply after it is two
        // bytes out of step. `probe` printed the counter's clock as
        // 20128-00-26 that way, straight after a recording killed `watch`.
        // So say stop first, whatever state it was left in.
        port.flush_input();
        let _ = port.write_all(b"<HEARTBEAT0>>");
        std::thread::sleep(Duration::from_millis(200));
        port.flush_input();
        if port.write_all(b"<GETVER>>").is_err() {
            continue;
        }
        // FOURTEEN BYTES IS THE OLD MODELS' ANSWER, NOT EVERY MODEL'S. A
        // GMC-320 replies "GMC-320Re 4.26", which is exactly 14, and this read
        // exactly 14 for years and was right every time. A GMC-320+ V4 replies
        // "GMC-320+V4Re 4.83", which is 17: the version came out truncated to
        // "GMC-320+V4Re 4" -- a firmware that does not exist -- and three
        // bytes were left sitting in the input buffer for whatever asked next.
        //
        // So take the 14 that are certainly there, then keep taking whatever
        // else arrives until it stops. The short second deadline is what keeps
        // this from costing a second per port on every model that answers in
        // 14: nothing more is coming, and 120 ms is long enough to be sure of
        // that at 115200 baud.
        let mut raw = port.read_exact_or_timeout(14, Duration::from_millis(1000));
        loop {
            let more = port.read_exact_or_timeout(16, Duration::from_millis(120));
            if more.is_empty() {
                break;
            }
            raw.extend_from_slice(&more);
            if raw.len() > 64 {
                break;
            }
        }
        let text = String::from_utf8_lossy(&raw).trim().to_string();
        if text.is_empty() || !text.to_uppercase().contains("GMC") {
            continue;
        }
        port.flush_input();
        let _ = port.write_all(b"<GETSERIAL>>");
        let s = port.read_exact_or_timeout(7, Duration::from_millis(1000));
        let serial_no = if s.len() == 7 {
            s.iter().map(|b| format!("{:02X}", b)).collect()
        } else {
            "unknown".to_string()
        };
        return Ok(Some(Counter {
            port,
            version: text,
            serial_no,
            path: path.to_string(),
            baud: rate,
        }));
    }
    Ok(None)
}

/// The model out of a firmware string.
///
/// A FREE FUNCTION, because `probe` can now learn what the counter is from the
/// service holding it rather than from the port, and all it gets that way is
/// the version string. Both paths must name the same model or the two probes
/// disagree about one counter.
pub fn model_of(version: &str) -> String {
    for m in ["GMC-320", "GMC-300", "GMC-500", "GMC-600"] {
        if version.contains(m) {
            return m.to_string();
        }
    }
    version.split_whitespace().next().unwrap_or("unknown").to_string()
}

/// Every counter on the machine, not just the first.
///
/// WHY THIS IS SEPARATE FROM `find`. One counter is still the ordinary case
/// and `find` is still what `probe`, `clock` and `log pull` want: those ask a
/// counter a question and there is no sense in which two of them answer it.
/// Collecting is different -- two tubes watching the same room are two
/// independent measurements of one number, and the whole point of reading both
/// is that averaging them is more precise than either. So the collector finds
/// all of them and everything else finds one.
///
/// Returns what it found, and -- only when that is nothing -- why.
/// One port, identified, or None for anything that is not a counter we can
/// have -- not a GMC, not answering, or locked by somebody else.
///
/// THE LOCK IS THE FILTER. A port this process already holds fails at the
/// flock exactly as another process's would, so a rescan can simply try every
/// candidate and let the ones it already has fall out. That costs one open
/// and one close per port per scan and needs no bookkeeping to go stale.
pub fn open_at(path: &str, baud: Option<u32>) -> Option<Counter> {
    identify(path, baud).ok().flatten()
}

pub fn find_all(devices: &[String], baud: Option<u32>) -> (Vec<Counter>, Option<NotFound>) {
    let ports: Vec<String> = if devices.is_empty() {
        candidate_ports()
    } else {
        devices.to_vec()
    };
    let mut found = Vec::new();
    let mut busy = Vec::new();
    for p in &ports {
        match identify(p, baud) {
            Ok(Some(c)) => found.push(c),
            Ok(None) => {}
            Err(OpenError::Busy) => busy.push(p.clone()),
            Err(_) => {}
        }
    }
    if !found.is_empty() {
        return (found, None);
    }
    // Nothing: say why, in the same words `find` would have used, so one
    // failure does not have two vocabularies.
    let why = match find_in(&ports, baud, busy) {
        Ok(c) => return (vec![c], None),
        Err(e) => e,
    };
    (Vec::new(), Some(why))
}

pub fn find(device: Option<&str>, baud: Option<u32>) -> Result<Counter, NotFound> {
    let ports: Vec<String> = match device {
        Some(d) => vec![d.to_string()],
        None => candidate_ports(),
    };
    if ports.is_empty() {
        if !usb_serial_driver_present() {
            return Err(NotFound {
                reason: "no USB-serial driver in this kernel".into(),
                detail: "Alpine's linux-virt has no ch341/usbserial at all, so a\n\
                         counter plugged in here can never appear as /dev/ttyUSB0.\n\
                         linux-lts and linux-rpi carry the drivers."
                    .into(),
                busy: false,
            });
        }
        return Err(NotFound {
            reason: "no serial device is present".into(),
            detail: "Nothing matching /dev/ttyUSB* or /dev/ttyACM*.".into(),
            busy: false,
        });
    }
    find_in(&ports, baud, Vec::new())
}

/// The diagnosis, given the ports to try and any already known to be busy.
fn find_in(ports: &[String], baud: Option<u32>, mut busy: Vec<String>) -> Result<Counter, NotFound> {
    if busy.is_empty() {
        for p in ports {
            match identify(p, baud) {
                Ok(Some(c)) => return Ok(c),
                Ok(None) => {}
                Err(OpenError::Busy) => busy.push(p.clone()),
                Err(_) => {}
            }
        }
    }
    if !busy.is_empty() {
        return Err(NotFound {
            reason: "the port is already open by another radbeeper".into(),
            detail: format!(
                "{} is locked by another process that is not sharing it.\n\
                 Nothing is wrong with the counter -- something else is reading\n\
                 it. A `service` from this version hands the stream to anyone\n\
                 who asks and never produces this message, so the holder is a\n\
                 one-shot that wants the port to itself -- a `random`, a\n\
                 `backfill`, a `log pull` -- or a build from before the stream\n\
                 existed. Wait for it with --wait, or:\n\
                 doas rc-service radbeeper stop",
                busy.join(", ")
            ),
            busy: true,
        });
    }
    Err(NotFound {
        reason: "a serial device is present but is not a GMC counter".into(),
        detail: format!("Tried {}. None answered <GETVER>> with a GMC version.", ports.join(", ")),
        busy: false,
    })
}