poweroff_daemon
poweroff_daemon is a small Linux daemon that monitors a serial-attached power/fan control
module of a
single-board computer. The board is powered by four 18650 cells and an external 16.8 V supply. The daemon
polls the module for button state and conditional battery voltage and calls /sbin/poweroff when a shutdown
condition is detected.
The daemon is intended for headless systems where the power module must shut the computer down before the
batteries are deeply discharged, or when a physical BUTTON0 is pressed.
Features
- Polls a serial device for:
BUTTON0state;V12voltage value (in arbitrary units, not hundreds of Volts!).
- Triggers
/sbin/poweroffwhen:BUTTON0is pressed;V12falls below the configured low-voltage threshold.
- Runs as a daemon.
- Supervises a child process and restarts it if it exits unexpectedly.
- Provides a UNIX-domain socket for sending custom commands to the serial device.
- Supports optional logging to a file.
- Uses newline-terminated serial protocol (
\n, no\r).
Project files
| File | Purpose |
|---|---|
main.c |
Program entry point, daemonization, child supervision, main polling loop, poweroff trigger. |
cmdlnopts.c / cmdlnopts.h |
Command-line option parsing and default configuration values. |
serial.c / serial.h |
Serial port handling, command/response parsing, button and voltage checks. |
server.c / server.h |
UNIX-domain socket server and request handlers. |
Requirements
- Linux.
- C compiler and build tools.
usefull_macroslibrary.pthreadsupport.- A serial device connected to the power/fan control module, usually
/dev/ttyUSB0. - Root privileges or suitable permissions for:
- opening the serial device;
- executing
/sbin/poweroff; - creating the PID file and socket, depending on paths.
Build with make commands, supporting several targets:
release(default) - release build;debug- build with debugging on;clean- clear temporarily build files;xclean- also clean binary file.
There's no option install, so you should manually copy binary file into some destination.
Usage
./poweroff_daemon [options]
Example:
./poweroff_daemon \
--device /dev/ttyUSB0 \
--baudrate 115200 \
--interval 1.0 \
--sockpath @poweroffdaemon \
--log /var/log/poweroff_daemon.log \
--verbose
The daemon normally needs to run as root because it calls /sbin/poweroff.
Command-line options
| Short | Long | Argument | Default | Description |
|---|---|---|---|---|
-p |
--pidfile |
string | /tmp/powerdaemon.pid |
PID file path. |
-l |
--log |
string | none | Log file path. If not set, no logging. |
-i |
--interval |
double | 1.0 |
Poll interval in seconds. |
-t |
--timeout |
double | 100000 |
Serial read timeout in microseconds. |
-v |
--verbose |
none | warning level | Increases verbosity. Each -v adds a level. |
-d |
--device |
string | /dev/ttyUSB0 |
Serial device path. |
-b |
--baudrate |
integer | 115200 |
Serial baudrate. For USB CDC devices this is often irrelevant. |
-s |
--sockpath |
string | @poweroffdaemon |
UNIX-domain socket path. The leading @ means the Linux abstract socket namespace. |
-h |
--help |
none | Show help and exit. |
Serial protocol
The daemon communicates with the power/fan module using newline-terminated text commands. Only \n is used
as a line separator; \r is not expected.
Built-in commands:
| Command | Expected key | Meaning |
|---|---|---|
B\n |
BUTTON0 |
Read button state. A non-zero value triggers poweroff. |
V\n |
V12 |
Read voltage value. |
For more information read documentation for power/fan control module.
Responses are parsed line by line. Each relevant line is expected to contain a key/value pair, for example:
BUTTON0 = 0
V12 = 1200
For USB CDC serial devices, port settings such as baudrate and data format are usually ignored by the device.
The --baudrate option is retained for compatibility or connection over USB-UART adapter.
Shutdown conditions
The current code triggers poweroff when either condition is true:
BUTTON0value is non-zero.V12value is belowLOWEST_V12.
Relevant constants are defined in serial.h:
#define CMD_BTNCHECK "B\n"
#define ANS_BTN0STATE "BUTTON0"
#define CMD_GETVOLTAGE "V\n"
#define ANS_V12 "V12"
#define LOG_V12 1150
#define LOG_VOLTAGE_DT 60
#define LOWEST_V12 970
#define MAX_WERR_CNT 5
#define MAX_RERR_CNT 15
The code logs voltage (in arbitrary units depending on voltage divider configuration) as:
(double)voltage / 100.
For current device configuration value of 11.73 V means 16.8 V.
So with the current constants, LOWEST_V12 == 970 is logged as 9.70 V (near 13.9 V for my configuration)
and LOG_V12 == 1150 is logged as 11.50 V (near 16.5 V - started working after power lost). Verify that
these values match the actual units and safe thresholds of your battery pack and power module before
deploying the daemon.
Additional behavior:
- If
V12is belowLOG_V12but not belowLOWEST_V12, the voltage is logged at most once perLOG_VOLTAGE_DTseconds. - When voltage returns above
LOG_V12, a "power restored" message is logged. - The current implementation does not implement multi-sample confirmation, debounce, or hysteresis. A single reading can trigger poweroff.
UNIX socket interface
The daemon starts a UNIX-domain socket server. By default it uses the Linux abstract socket name:
@poweroffdaemon
Clients can connect and send text commands.
Default behavior:
- Any message received by the default handler is forwarded to the serial device.
- The serial response is sent back to the client.
- The special request
_helpsends the literal commandhelpto the serial device and returns its response.
Important: the socket interface currently forwards arbitrary client input to the serial device. It does not implement authentication or command filtering. On a multi-user system, use a filesystem socket with restrictive permissions or add peer credential checks and a command whitelist.
Runtime behavior
-
The program initializes logging and parses command-line options.
-
It checks whether another instance is already running using the PID file.
-
If a log file is configured, it opens the log.
-
The process daemonizes.
-
The parent process supervises a child process:
- if the child exits, the parent waits 5 seconds and starts a new child;
- the parent logs child deaths.
-
The child process:
- sets
PR_SET_PDEATHSIGso that it receivesSIGTERMif the parent dies; - opens the serial device;
- starts the UNIX socket server;
- enters the polling loop.
- sets
-
On each poll, the child checks buttons and voltage.
-
If a shutdown condition is met, it logs the event and executes:
system("/sbin/poweroff"); -
On normal loop exit, it stops the socket server and closes the serial port.
Signals
The daemon handles SIGTERM, SIGINT, and SIGQUIT; SIGTSTP is ignored. SIGHUP ignored by sl_daemonize().
The current signal handler is simple and calls logging and cleanup functions directly. For production use, consider replacing it with an async-signal-safe handler that only sets a flag or writes to a self-pipe, and perform cleanup in the main loop.
Logging
Logging is implemented through usefull_macros.
- By default, the log level is warning.
- Each
--verboseoption increases the log level. - If
--logis specified, the daemon opens the given log file before daemonizing. - If the log file cannot be created, a warning is emitted.
Safety and deployment notes
This daemon can power off the machine. Before deploying it, verify the following:
- The
V12units and thresholds match your hardware. - The low-voltage threshold is safe for your four-cell battery pack.
- A single noisy reading cannot cause an unwanted shutdown, or add filtering/debounce if needed.
- Loss of serial communication has the desired behavior. In the current code, repeated serial errors cause
the child process to exit and be restarted by the parent; they do not directly call
poweroff. - The socket interface is appropriately protected.
- The PID file path is safe. The default
/tmp/powerdaemon.pidmay be unsuitable for a root daemon on a multi-user system. - Only one process can access the serial device. The current code does not set an exclusive serial lock.
/sbin/poweroffexists and works on the target system.
Usage example
Because the program daemonizes itself, you can run it over OpenRC's local service, creating bash-script
powerdaemon.start in /etc/local.d:
#!/bin/bash
/usr/local/sbin/powerdaemon -vvv -l /RAID/powerdaemon.log -p /tmp/powerdaemon.pid &
The main process doesn't run fork(), so you can start it even with supervise-daemon or other services.
Adjust paths, user, and permissions to match your system.
License
This project is licensed under the GNU General Public License, version 3 or later. See the source file headers for details.