small_tel/Daemons/domedaemon_baader/Readme.md

domedaemon_baader

domedaemon_baader is a daemon that controls a Baader Planetarium all‑sky dome via a serial line. It provides a TCP/UNIX socket interface for clients, integrates with a weather proxy to enforce safety rules, and generates a FITS‑style header file with current dome status and weather sensor data.

---

Features

• Dome open/close – fully open or close the dome
• Stop movement – immediately stop any ongoing dome motion
• Weather sensor integration – reads rain/cloud status from the dome’s internal sensor
• Error reporting – reports rain, timeout, and power‑loss error codes
• Weather proxy integration – automatically closes the dome and blocks opening when external weather is bad or data is stale
• Manual override – via SIGUSR1 (forbid) / SIGUSR2 (allow) signals
• FITS header file – writes current dome state and weather sensor status into a FITS‑style header file (e.g., for later use by image processing pipelines)
• Network interface – supports both INET (TCP) and UNIX domain sockets
• Daemon mode – forks, writes PID file, restarts child on crash

---

Command‑line options

Option	Argument	Default	Description
-h, --help	–	–	Show help
-d, --serialdev	path	–	Full path to serial device (e.g. /dev/ttyS1)
-n, --node	string	–	Node specification: IP, name:IP, or path for UNIX socket. For anonymous UNIX socket use \0path or @path.
-l, --logfile	path	–	Full path to log file
-u, --unixsock	–	0	Use UNIX socket instead of INET
-v, --verbose	–	0	Increase verbosity (each -v adds 1 level; 0: only errors, 1: +warnings, 2: +messages, 3: +debug info)
-p, --pidfile	path	/tmp/domedaemon.pid	PID file path
-H, --headerfile	path	/tmp/dome.fits	Output file for FITS‑style header
-N, --domename	name	Baader	Dome name inserted into the header
-b, --baudrate	speed	9600	Serial baud rate
-T, --sertmout	microseconds	5000	Serial read timeout (µs)
-m, --maxclients	number	2	Maximum number of simultaneously connected clients

---

Socket protocol

The daemon listens for text‑based commands on the configured socket. Each command returns one or more lines of output, terminated by newline (\n).

Commands

Command	Description	Example
open	Fully open dome (only if weather permits and observations not forbidden)	open
close	Fully close dome	close
stop	Immediately stop dome movement	stop
status	Get dome status and temperatures	status → (see example below)
weather	Get weather sensor status	weather → weather=good
dtime	Return server’s current UNIX time (seconds with milliseconds)	dtime → UNIXT=1704067200.123
help	Show available commands (default handler)	help

Each setter returns an OK answer in case of success or error code like BADVAL for bad value of setter.

Example status response

status=opened
measuret=1704067200.123
error=closed@timeout@powerloss
FORBIDDEN
BADWEATHER
errored_command=open

• status can be opened, closed, intermediate or unknown.
• measuret is the time when the status was last read from the hardware.
• error appears when the dome reports an error. It encodes up to three flags:
  • closed – base error (dome closed due to error)
  • @rain – rain sensor triggered
  • @timeout – watchdog timeout
  • @powerloss – power loss detected
• FORBIDDEN appears when observations have been manually disabled (SIGUSR1).
• BADWEATHER appears when weather proxy reports unsafe conditions.
• errored_command shows the last command that failed.

---

Weather integration

The daemon retrieves external weather data via the weather_proxy shared memory interface (get_weather_data()). Safety rules:

• If weather.forceoff, weather.rain, or weather.weather > WEATHER_BAD → dome is closed and opening is blocked.
• If the weather data is older than 300 seconds (WEATHER_LOST) → treated as lost communication → dome is closed and blocked.
• When weather becomes good again, the daemon automatically resets the BADWEATHER flag and allows normal operation.

The weather is polled every 5 seconds (T_INTERVAL).

---

Dome‑internal weather sensor

The daemon also reads the dome’s built‑in weather sensor via the d#ask_wea command.
Possible states:

• 0 → good (no rain/clouds)
• 1 → rain/clouds
• other → unknown

This status is written into the FITS header as DOMEWEAT.

---

Signal handling

Signal	Effect (in child process)
SIGUSR1	Forbid observations – close dome and block open
SIGUSR2	Allow observations – remove manual block
SIGTERM	Stop the daemon and remove PID file
SIGINT	Same as SIGTERM
SIGQUIT	Same as SIGTERM

---

FITS header file

The daemon writes a text file (default /tmp/dome.fits) with FITS‑like keyword/value pairs. The file is updated every polling cycle (every 5 seconds) and can be used by external pipelines to record dome state.

Example content:

OPERATIO= 'FORBIDDEN'           / Observations are forbidden
DOME    = 'Baader'              / Dome manufacturer/name
DOMESTAT= 'closed'              / Dome status
DOMEWEAT= 'good'                / Dome weather sensor status
DOMEECOD= 0                     / Dome error code: Rain|Watchdog|Power
TDOMMEAS= 1779091627.907        / Measurement time: 2026-05-18 11:07:07

The OPERATIO keyword appears only when observations are manually forbidden via SIGUSR1.

The file is created atomically using mkstemp() + rename().

---

Building and dependencies

Dependencies

• libusefull_macros – common macros and helpers
• libweather_proxy – shared memory weather data
• pthread, libc

Build

git clone --depth=1 https://github.com/eddyem/small_tel.git
cd small_tel/Daemons/domedaemon_baader
make

The resulting binary is domedaemon.

Installation

Copy the binary to a suitable location (e.g. /usr/local/bin).
It is recommended to run the daemon as a system service (using init script, e.g. in /etc/local.d/) so that it starts automatically at boot.

---

Usage example

Start the daemon with a TCP local-only socket and weather‑aware header:

domedaemon -d /dev/ttyS2 -l /var/log/telescope/domedaemon.log -vv \
    -n localhost:55555 -H /tmp/dome.fitsheader

Connect to the socket using socat, nc or my tty_term:

nc localhost 55555
> status

Send SIGUSR1 to forbid observations (e.g. before maintenance):

killall -USR1 domedaemon

Don't send signals USR1/USR2 to father process (its PID stored in pidfile): it simply ignores them. Send them by killall to both processes, or by kill to daughter process.

---

Notes

• The serial protocol is specific to Baader Planetarium hardware. Commands such as d#opendom, d#closdom, d#stopdom, d#get_dom, d#ask_wea, and d#warning are hard‑coded in commands.h.
• The dome returns numerical values:
  • Position codes: 1111 = fully opened, 2222 = fully closed, anything else = intermediate.
  • Weather codes: 0 = good, 1 = rain/clouds, other = unknown.
  • Error codes are bit‑encoded: 1 = rain, 10 = timeout, 100 = power loss.
• The daemon polls the dome every 5 seconds (T_INTERVAL). During that interval it also processes client requests and checks external weather.
• If the serial device becomes unresponsive, the status will show unknown and the header will not be updated.

---

License

GNU General Public License v3.0 or later. See the LICENSE file in repository's root directory or http://www.gnu.org/licenses/ for details.