Generated LinuxCNC HAL Rust bindings
Please consider becoming a sponsor so I may continue to maintain this crate in my spare time!
Documentation
This crate provides generated bindings for LinuxCNC's HAL using bindgen
.
The high level, safe interface at linuxcnc-hal
is recommended for user code.
Development setup
bindgen
must be set up correctly. Follow the
requirements section of its docs.
To run and debug any HAL components, the LinuxCNC simulator can be set up. There's a guide here for Linux Mint (and other Debian derivatives).
Project setup
The LINUXCNC_SRC
environment variable is required to build this crate. The value must be the
absolute path to the root of the LinuxCNC source code.
The version of the LinuxCNC sources must match the LinuxCNC version used in the machine control.
# Clone LinuxCNC source code into linuxcnc/
# Check out a specific version tag. This may also be a commit, but must match the version in use by the machine control.
&& &&
# Create your component lib
# Add LinuxCNC HAL bindings as a Cargo dependency with cargo-edit
LINUXCNC_SRC=/path/to/linuxcnc/source/code
Examples
Running the examples in the LinuxCNC simulator
Ensure you have the LinuxCNC source repository cloned, checked out to the desired version and built with the build instructions.
Note that the LinuxCNC source is located in the same parent directory as linuxcnc-hal-rs
in
the example paths below.
LINUXCNC_SRC=
# Define the correct path to the LinuxCNC source
All functions exported from this crate are unsafe
, hence each example is wrapped in a big
unsafe
block for clarity.
The LinuxCNC HAL requires a certain setup procedure to operate correctly. The basic program structure should be roughly as follows:
- Call
hal_init
to create a new HAL component - Register
SIGTERM
andSIGINT
signals, likely with thesignal_hook
crate. LinuxCNC will hang if these signals are not registered. - Register pins with
hal_pin_float_new
,hal_pin_u32_new
, etc - Call
hal_ready
to signal to LinuxCNC that the component is ready - Enter an infinite loop to continuously update input/output pin values and perform component logic
These examples can be loaded into LinuxCNC using a HAL file similar to this:
loadusr -W /path/to/your/component/target/debug/comp_bin_name
net input-1 spindle.0.speed-out pins.input-1
If LinuxCNC is configured to run in place, liblinuxcnchal.so.0
may not be found on startup. To
fix, try setting the library path with e.g. export LD_LIBRARY_PATH=~/Repositories/linuxcnc/lib
Create an input pin
This example creates a component called pins
and registers an input pin to it that accepts a
floating point value using hal_pin_float_new
. Each HAL pin requires some memory allocated to
store its value which is performed with hal_malloc
.
The example can be loaded into LinuxCNC using a HAL file similar to this:
Note that there is no error handling in this example for brevity.
use *;
use Signals;
use CString;
use mem;
use thread;
use Duration;
unsafe
Error handling
Errors are handled in this crate the same way as in the C code. Some consts are exported like
EINVAL
and EPERM
to allow matching of returned error codes.
use *;
use Signals;
use CString;
use mem;
use thread;
use Duration;
unsafe
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.