Skip to content

HAL Interface

Jump to bottom
Dominik Zarfl edited this page Apr 26, 2025 · 5 revisions

HAL Interface

Pokeys Pin

image

Count: 55

Parameters

  • pokeys.[DevID].Pin.[PinID].PinFunction int PinFunction to be set for corresponding pin see ePK_PinCap

the PinFunction can be set using followin enumeration. Note that e.g. digitalInput or digitalOutput could be directly inverted on pokeys by adding value 128 (PK_PinCap_digitalOutput+PK_PinCap_invertPin or 2 + 128 = 130):

add. Note: for PK_PinCap_analogOutput has not been used so far currently only PWM functionality has been used instead that is what is being used for (pins 18, 20, 21 and 22)

      enum ePK_PinCap
      {
          PK_PinCap_pinRestricted  = 0,           // Pin is not used
          PK_PinCap_reserved       = 1,           // --
          PK_PinCap_digitalInput   = 2,           // Digital input
          PK_PinCap_digitalOutput  = 4,           // Digital output
          PK_PinCap_analogInput    = 8,           // Analog input (only on selected pins)
          PK_PinCap_analogOutput   = 16,          // Analog output (only on selected pins)
          PK_PinCap_triggeredInput = 32,          // Triggered input
          PK_PinCap_digitalCounter = 64,          // Digital counter (only on selected pins)
          PK_PinCap_invertPin      = 128          // Invert digital pin polarity (set together with digital input, output or triggered input)
      };

Digital Input

Count: 55

Pins

  • pokeys.[DevID].digin.[PinID].in bit State of the hardware input
  • pokeys.[DevID].digin.[PinID].in-not bit Inverted state of the input.

Parameters

  • pokeys.[DevID].digin.[PinID].invert bit invert Pin on pokeys using PK_PinCap_invertPin on PinFunction

Digital Output

Count: 55

Pins

  • pokeys.[DevID].digout.[PinID].out bit Value to be written (possibly inverted) to the hardware output

Parameters

  • pokeys.[DevID].digout.[PinID].invert bit invert Pin on pokeys using PK_PinCap_invertPin on PinFunction

Analog Input

Count: 7

Pins

  • pokeys.[DevID].adcin.[AdcId].value-raw float The hardware reading
  • pokeys.[DevID].adcin.[AdcId].value float The hardware reading, scaled according to the scale and offset parameters

Parameters

  • pokeys.[DevID].adcin.[AdcId].scale float The input voltage (or current) will be multiplied by scale before being output to value
  • pokeys.[DevID].adcin.[AdcId].offset float This will be subtracted from the hardware input voltage (or current) after the scale multiplier has been applied

Analog Output (PWM)

image

Count: 6

Pins

  • pokeys.[DevID].adcout.[AdcId].value: The value to be written. The actual value output to the hardware will depend on the scale and offset parameters
  • pokeys.[DevID].adcout.[AdcId].enable: If false, then output 0 to the hardware, regardless of the value pin

Parameters

  • pokeys.[DevID].adcout.[AdcId].offset: This will be added to the value before the hardware is updated
  • pokeys.[DevID].adcout.[AdcId].scale: This should be set so that an input of 1 on the value pin will cause 1V
  • pokeys.[DevID].adcout.[AdcId].high_limit: When calculating the value to output to the hardware, if value + offset is greater than high_limit, then high_limit will be used instead
  • pokeys.[DevID].adcout.[AdcId].low_limit: When calculating the value to output to the hardware, if value + offset is less than low_limit, then low_limit will be used instead
  • pokeys.[DevID].adcout.[AdcId].max_v: Max output voltage
  • pokeys.[DevID].adcout.pwm.period: PWM period, shared among all channels

Encoder

Count: 29

Pins

  • pokeys.[DevID].encoder.[EncId].count; S32 Encoder value in counts.
  • pokeys.[DevID].encoder.[EncId].position; FLOAT Encoder value in position units (see parameter “scale”).
  • pokeys.[DevID].encoder.[EncId].velocity; FLOAT Velocity in position units per second
  • pokeys.[DevID].encoder.[EncId].reset; BIT When True, force counter to zero
  • pokeys.[DevID].encoder.[EncId].index-enable; BIT (bidirectional) When True, reset to zero on next index pulse, and set pin False.

Parameters

  • pokeys.[DevID]. encoder.[EncId].scale FLOAT "The scale factor used to convert counts to position units. It is in “counts per position unit”";

⚙️ HAL Interface — Encoders

HAL Pins (per encoder.N)

HAL Pin Type Direction Description
encoder.N.count s32 OUT Raw encoder count
encoder.N.position float OUT Scaled encoder position
encoder.N.velocity float OUT Calculated velocity
encoder.N.reset bit IN Reset encoder count
encoder.N.index-enable bit IO Index pulse based reset synchronization

HAL Parameters (per encoder.N)

HAL Parameter Type Description
encoder.N.enable bit Enable encoder input
encoder.N.scale float Position scaling (units/count)
encoder.N.channelApin u32 Channel A physical pin assignment
encoder.N.channelBpin u32 Channel B physical pin assignment
encoder.N.x2_sampling bit Enable x2 sampling mode
encoder.N.x4_sampling bit Enable x4 sampling mode
encoder.N.keymap_dirA bit Direct key mapping for direction A
encoder.N.macro_dirA bit Map direction A to macro
encoder.N.keymap_dirB bit Direct key mapping for direction B
encoder.N.macro_dirB bit Map direction B to macro

📄 INI Configuration

You can configure encoder parameters in your LinuxCNC INI file under the [POKEYS] section.

Example for encoder.0 (typical MPG jog wheel at 100 PPR):

[POKEYS]
encoder.0.enable = 1
encoder.0.scale = 0.01
encoder.0.channelApin = 8
encoder.0.channelBpin = 12
encoder.0.x4_sampling = 1
encoder.0.x2_sampling = 0
encoder.0.keymap_dirA = 0
encoder.0.macro_dirA = 0
encoder.0.keymap_dirB = 0
encoder.0.macro_dirB = 0

Notes:

  • channelApin is the PoKeys pin number for Channel A input.
  • channelBpin is the PoKeys pin number for Channel B input.
  • For most encoders, enable x4 sampling for full quadrature resolution.
  • keymap_dirA, macro_dirA, keymap_dirB, and macro_dirB are normally disabled unless using special PoKeys keyboard/macro features.

⚠️ Known Limitations

  • Index pulse reset: While an index-enable pin exists for each encoder in HAL, the PoKeys hardware/firmware does not automatically reset the encoder count on index pulse.
    Manual reset must be handled via LinuxCNC HAL logic if needed.
  • Fast/UltraFast Encoders: Special configuration options are available separately (see Fast and UltraFast Encoders).

Real-Time Clock

Pins

  • pokeys.[DevID].rtc.sec: Second
  • pokeys.[DevID].rtc.min: Minute
  • pokeys.[DevID].rtc.hour: Hour
  • pokeys.[DevID].rtc.dow: Day of week
  • pokeys.[DevID].rtc.dom: Day of month
  • pokeys.[DevID].rtc.doy: Day of year
  • pokeys.[DevID].rtc.month: Month
  • pokeys.[DevID].rtc.year: Year
  • pokeys.[DevID].rtc.loop_frequ: Actual loop frequency of pokeys.comp updated after rtc.sec changed
  • pokeys.[DevID].rtc.loop_frequ_demand: Demand value for loop frequency (if 0, default of 10Hz will be used)

Pulse Engine

image

Pulse Generator options

image

Motion Parameters

image

Emergency Pin

Limit Switches

image

Home/Ref switch

image

Axis enable output pin

image

Aux. outputs

image

This section provides access to external Relay and Open-Collector (OC) outputs available on PoKeys devices that support Pulse Engine v2 (PEv2).

HAL Pins

The following HAL output pins are exposed by the component:

Relay Outputs

pokeys.[DevID].PEv2.digout.ExternalRelay-0.out pokeys.[DevID].PEv2.digout.ExternalRelay-1.out pokeys.[DevID].PEv2.digout.ExternalRelay-2.out pokeys.[DevID].PEv2.digout.ExternalRelay-3.out

OC Outputs

pokeys.[DevID].PEv2.digout.ExternalOC-0.out pokeys.[DevID].PEv2.digout.ExternalOC-1.out pokeys.[DevID].PEv2.digout.ExternalOC-2.out pokeys.[DevID].PEv2.digout.ExternalOC-3.out

These pins correspond to the checkboxes shown in the Aux. outputs section of the PoKeys configuration utility:

Relay Outputs

UI Label HAL Pin PoKeys57CNC PoKeys57CNCpro4x25 PoKeysCNCaddon
0 pokeys.[DevID].PEv2.digout.ExternalRelay-0.out SSR1 FAN Control Relay1
1 pokeys.[DevID].PEv2.digout.ExternalRelay-1.out SSR2 Plasma Relay Relay2
2 pokeys.[DevID].PEv2.digout.ExternalRelay-2.out Relay1 Relay1 Relay3
3 pokeys.[DevID].PEv2.digout.ExternalRelay-3.out Relay2 Relay2 Relay4

Open-Collector (OC) Outputs

UI Label HAL Pin PoKeys57CNC PoKeys57CNCpro4x25 PoKeysCNCaddon
0 pokeys.[DevID].PEv2.digout.ExternalOC-0.out OC1 OC1 OC1
1 pokeys.[DevID].PEv2.digout.ExternalOC-1.out OC2 OC2 OC2
2 pokeys.[DevID].PEv2.digout.ExternalOC-2.out OC3 OC3 OC3
3 pokeys.[DevID].PEv2.digout.ExternalOC-3.out OC4 OC4 OC4

ℹ️ Note: These mappings are automatically applied at runtime based on the detected device type. You don't need to change your HAL file — the component ensures correct hardware control behind the scenes.

Example Usage

You can assign a logical signal to control a relay like this:

net floodlight-control => pokeys.0.PEv2_digout_ExternalRelay_out[2]

MPG jog setup

image

Pulse Engine State

image

Parameters

Clone this wiki locally