'\" t
.\"     Title: enum
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 03/13/2024
.\"    Manual: LinuxCNC Documentation
.\"    Source: LinuxCNC
.\"  Language: English
.\"
.TH "ENUM" "9" "03/13/2024" "LinuxCNC" "LinuxCNC Documentation"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
enum \- enumerate integer values into bits
.SH "SYNOPSIS"
.sp
\fBloadrt enum enums=E;enum1pin1;enum1pin2;;;enum1pin3,D;;;enum2pin1;enum2pin2 [names=name1,name2]\fR
.SH "DESCRIPTION"
.sp
\fBenum\fR converts integer values into bits and vice versa\&.
.sp
The component is especially suitable for encoding and decoding register values for modbus devices, where control commands and status are frequently encoded as enumerations rather than bits\&. For example 0 = stop, 1 = forwards, 2 = backwards, 3 = jog\-forwards etc\&.
.sp
The pins created and the behaviour of the component are controlled by the load\-time modparams "enums=" and "names="
.sp
The \fBenums=\fR parameter should be a comma\-separated list of semicolon\- separated pin labels\&. The enumerated values will increase in sequence starting at zero\&. To skip a value use a zero\-length label, ie two consecutive semicolons, as shown in the examples\&.
.sp
There should be no spaces in the "enums=" list\&.
.sp
"names=" is an optional list of component instance names\&. If "names=" is omitted the functions and pins will be named "enum\-decode\&...\&." or "enum\-encode\&...\&."
.sp
Taking the example configuration above, if \fBenum\-decode\&.01\&.enum2pin1\-in\fR is set to \fBTRUE\fR then the output pin \fBenum\-decode\&.01\&.output\fR will be set to the value 2\&. If \fBenum\-decode\&.01\&.enum2pin2\-in\fR is set to true then the output would be 3\&.
.sp
Conversely, if \fBenum\-encode\&.00\&.input\fR is set to 4 then the pin \fBenum\-encode\&.00\&.enum1pin3\-out\fR will be set to \fBTRUE\fR\&.
.SH "OPTIONS"
.sp
Preceding the list of labels should be the control\-codes "D" for decode or "E" for encode\&. A D\-type enum will set the value of HAL bit pins in response to changes to the enum\-decode\&.NN\&.input value, whereas an E\-type enum will set the value of the enum\-encode\&.NN\&.output integer depending on which enum\-encode\&.NN\&.label\-bit value is set\&.
.sp
If more than one label\-bit input pin is set the output value will correspond to the pin label later in the list\&.
.sp
E and D\-type enumerations may be freely mixed in separate instances\&.
.SH "FUNCTIONS"
.sp
\fBenum\-decode\&.\fR\fB\fINN\fR\fR \- if instance type = "D"
.sp
\fBenum\-encode\&.\fR\fB\fINN\fR\fR \- if instance type = "E"
.SH "PINS"
.sp
\fBenum\-decode\&.\fR\fB\fINN\fR\fR\fB\&.input\fR \- The integer value to be decoded
.sp
\fBenum\-decode\&.\fR\fB\fINN\fR\fR\fB\&.label\-out\fR \- output bits of a decode instance
.sp
\fBenum\-decode\&.\fR\fB\fINN\fR\fR\fB\&.label\-val\fR \- The enumeration value corresponding to each specific bit output\&. These are populated in sequence during loading but may be over\-ridden in HAL if convenient\&.
.sp
\fBenum\-encode\&.\fR\fB\fINN\fR\fR\fB\&.label\-in\fR \- input bits of a decode instance
.sp
\fBenum\-encode\&.\fR\fB\fINN\fR\fR\fB\&.label\-val\fR \- The enumeration value corresponding to each specified bit input\&. These are populated in sequence during loading but may be over\-ridden in HAL if convenient\&.
.sp
\fBenum\-decode\&.\fR\fB\fINN\fR\fR\fB\&.output\fR \- The integer value corresponding to the set bit input\&.
.SH "BUGS"
.sp
If no bits are set the output value will be zero even if zero is a defined enumeration\&.
.SH "AUTHOR"
.sp
Andy Pugh
.SH "REPORTING BUGS"
.sp
Report bugs to at the LinuxCNC github issues list: https://github\&.com/LinuxCNC/linuxcnc/issues
.SH "COPYRIGHT"
.sp
Copyright \(co 2023 Andy Pugh\&. This is free software; see the source for copying conditions\&. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE\&.