/** @page x52d_protocol X52 daemon socket communication protocol The X52 daemon creates a Unix domain stream socket, by default at `$(LOCALSTATEDIR)/run/x52d.cmd` and listens for connection requests from clients at this location. This can be overridden by passing the -s flag when starting the daemon. # Protocol Overview \b x52d requires that clients send it commands as a series of NUL terminated strings, without any interleaving space. The command should be sent in a single `send` call, and the client may expect a response in a single `recv` call. The `send` call must send exactly the number of bytes in the command text. Extra bytes will be treated as additional arguments, which would cause the command to fail. It is recommended that the `recv` call uses a 1024 byte buffer to read the data. Responses will never exceed this length. # Responses The daemon sends the response as a series of NUL terminated strings, without any interleaving space. The first string is always one of the following: - \c OK - \c ERR - \c DATA This determines whether the request was successful or not, and subsequent strings describe the action, error or requested data. # Examples ## Reloading configuration - \b send config\0reload\0 - \b recv OK\0config\0reload\0 ## Reading mouse speed - \b send config\0get\0mouse\0speed\0 - \b recv DATA\0mouse\0speed\010\0 ## Sending an invalid command - \b send config reload - \b recv ERR\0Unknown command 'config reload'\0 # Commands \b x52d commands are arranged in a hierarchical fashion as follows: ``` [ [ [...]]] [] ``` The list of supported commands are shown below: - @subpage proto_config - @subpage proto_logging */ /** @page proto_config Configuration management The \c config commands deal with \b x52d configuration subsystem, and have the following subcommands. @tableofcontents # Load configuration The `config load` subgroup allows you to load a configuration from a given file (discarding anything that was already in memory), or reload the configuration from the command-line specified configuration file (or default configuration file if no option was given on the command line.) ## Load from file \b Arguments - `config` - `load` - \a path-to-file \b Returns - `OK` - `config` - `load` - \a path-to-file \b Error - `ERR` - Invalid file '/none' for 'config load' command ## Reload system configuration \b Arguments - `config` - `reload` \b Returns - `OK` - `config` - `reload` # Save configuration The `config save` subgroup requests the \b x52d daemon to save the current state of the configuration to disk. This is either the system configuration file, or may be a user specified configuration file. Note that this will be created with the permissions of the running daemon, which may be running as root. ## Dump configuration to file \b Arguments - `config` - `dump` - \a path-to-file \b Returns - `OK` - `config` - `dump` - \a path-to-file \b Error - `ERR` - Invalid file '/none' for 'config dump' command ## Save system configuration \b Arguments - `config` - `save` \b Returns - `OK` - `config` - `save` # Retrieve configuration parameter The `config get` command requests a specific configuration value, given the section and the key. Refer to \ref x52d for the section and key names, as these are derived from the base configuration. \b Arguments - `config` - `get` - \a section - \a key \b Returns - `DATA` - \a section - \a key - \a value \b Example ``` DATA\0mouse\0enabled\0true\0 ``` Error example ``` ERR\0Error getting 'foo.bar'\0 ``` # Set configuration parameter The `config set` command requests the \b x52d daemon to set the given (section, key) parameter to the given value. The daemon will treat it the same way as if it was being read from the configuration file, i.e., it will follow identical parsing logic, including ignoring unknown keys and not reporting errors for them. A side effect of this is that the client could request a set for any arbitrary section and key pair, and if that pair was not recognized, it would be ignored, but the daemon would still send an `OK` response. Finally, this will only set the value within the configuration memory structures, and will not invoke any callback to update the rest of the threads or device state. The client will need to call the `apply` subcommand to actually invoke the necessary callbacks. \b Arguments - `config` - `set` - \a section - \a key - \a value \b Returns - `OK` - `config` - `set` - \a section - \a key - \a value Error example ``` ERR\0Error 22 setting 'led.fire'='none': Invalid argument\0 ``` # Apply configuration The `config apply` command will invoke all the callbacks and ensure that the configuration is applied to the running state. \b Arguments - `config` - `apply` \b Returns - `OK` - `config` - `apply` */ /** @page proto_logging Logging management The \c logging commands allow the user to fine tune the logging configuration of \c x52d as well as adjust the log levels for either all the modules, or for each of the modules individually. While the `-v` and `-q` command line options allow you to either increase the logging verbosity or suppress it entirely, they are required to be specified at program startup. On the other hand, having the `logging` commands allows the user to fine tune the logging while the daemon is running. @tableofcontents # Modules \c x52d is split into several modules as far as logging is concerned. The list of modules is below: - \c Config - \c Clock - \c Command - \c Device - \c IO - \c LED - \c Mouse # Logging levels The following is a list of supported logging levels. Each level logs the ones above it as well as the current level - \c none - Disable logging entirely - \c fatal - Log fatal messages - \c error - Log error messages - \c warning - Log warning messages - \c info - Log informational messages - \c debug - Log debug messages - \c trace - Log trace messages - useful for tracing program flow. - \c default - Not a level, but used when configuring module log levels, makes the module log level fallback to the global log level. # Show logging configuration The `logging show` command takes in an optional module name, as listed in the Modules section above. It returns the module name, if specified, and the log level for that module. If the module is configured to fallback to the global level, then it will return the global level. \b Arguments - `logging` - `show` - \a module-name (Optional) \b Returns - `DATA` - \a module-name (if specified) - \a log-level # Set logging configuration The `logging set` command takes in the optional module name and the log level and sets the log level for that module, if specified, or the global level otherwise. \b Arguments - `logging` - `set` - \a module-name (Optional) - \a log-level \b Returns - `OK` - `logging` - `set` - \a module-name (if specified) - \a log-level */