Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
Generated LinuxCNC HAL Rust bindings
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.
Binding versions
This crate | LinuxCNC version |
---|---|
Any version greater than v0.1.7 | Provide a path to the LinuxCNC source code with LINUXCNC_SRC |
v0.1.7 | v2.7.15 |
v0.1.6 | v2.7.15 |
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
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
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.