= enum(9)

== NAME

enum - enumerate integer values into bits

== SYNOPSIS

*loadrt enum enums=E;enum1pin1;enum1pin2;;;enum1pin3,D;;;enum2pin1;enum2pin2 [names=name1,name2]*

== DESCRIPTION

*enum* converts integer values into bits and vice versa.

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.

The pins created and the behaviour of the component are controlled by
the load-time modparams "enums=" and "names="

The *enums=* 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.

There should be no spaces in the "enums=" list.

"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...."

Taking the example configuration above, if *enum-decode.01.enum2pin1-in*
is set to *TRUE* then the output pin *enum-decode.01.output* will be set
to the value 2. If *enum-decode.01.enum2pin2-in* is set to true then the
output would be 3.

Conversely, if *enum-encode.00.input* is set to 4 then the pin
*enum-encode.00.enum1pin3-out* will be set to *TRUE*. 

== OPTIONS

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.

If more than one label-bit input pin is set the output value will
correspond to the pin label later in the list.

E and D-type enumerations may be freely mixed in separate instances. 

== FUNCTIONS

*enum-decode._NN_* - if instance type = "D"

*enum-encode._NN_* - if instance type = "E"

== PINS

*enum-decode._NN_.input* - The integer value to be decoded

*enum-decode._NN_.label-out* -  output bits of a decode instance

*enum-decode._NN_.label-val* -  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.

*enum-encode._NN_.label-in*  -  input bits of a decode instance

*enum-encode._NN_.label-val* -  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.
                                
*enum-decode._NN_.output* - The integer value corresponding to the
                                set bit input.

== BUGS

If no bits are set the output value will be zero even if zero is a
defined enumeration.

== AUTHOR

Andy Pugh

== REPORTING BUGS
Report bugs to at the LinuxCNC github issues list:
https://github.com/LinuxCNC/linuxcnc/issues

== COPYRIGHT
Copyright © 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.

