search

zarfld / LinuxCnc_PokeysLibComp

Pokeys comp for LinuxCnc using https://bitbucket.org/mbosnak/pokeyslib.git
MIT License
5 stars 0 forks source link

readme

LinuxCnc_PokeysLibComp

Overview

The LinuxCnc_PokeysLibComp project integrates PoKeys devices with LinuxCNC, providing real-time control and monitoring capabilities. This repository contains the necessary components, scripts, and documentation to set up and use PoKeys devices with LinuxCNC.

Directory Structure

The repository is organized into the following directories:

Installation

To install the LinuxCnc_PokeysLibComp project, follow these steps:

git clone https://github.com/zarfld/LinuxCnc_PokeysLibComp.git
cd LinuxCnc_PokeysLibComp
sudo sh install.sh

Hardware Requirements

The project has been tested with the following hardware:

Library Status

The following features have been implemented and tested:

HAL Interface

Digital Input

Count: 55

Pins

Parameters

Digital Output

Count: 55

Pins

Parameters

Analog Input

Count: 7

Pins

Parameters

Analog Output

Count: 6

Pins

Parameters

Encoder

Count: 29

Pins

Parameters

Real-Time Clock

Pins

Running Tests

To ensure the reliability and correctness of the pokeys_py component, a comprehensive test suite has been developed. The tests cover various functionalities, including digital I/O, analog I/O, PEv2, counters, PWM outputs, and peripheral devices. The tests are categorized into unit tests, integration tests, functional tests, and performance tests.

Prerequisites

Before running the tests, make sure you have the following prerequisites installed:

You can install pytest using pip:

pip install pytest

Running Unit Tests

Unit tests are designed to test individual functions and methods within the pokeys_py component. To run the unit tests, navigate to the tests directory and execute the following command:

pytest test_analog_io.py
pytest test_counter.py
pytest test_digital_io.py
pytest test_pev2_motion_control.py
pytest test_ponet.py
pytest test_pwm.py

Running Integration Tests

Integration tests verify the interaction between the pokeys_py component and the PoKeys hardware and LinuxCNC. To run the integration tests, execute the following command:

pytest test_integration.py

Running Functional Tests

Functional tests simulate real-world usage scenarios for the pokeys_py component. To run the functional tests, execute the following command:

pytest test_functional.py

Running Performance Tests

Performance tests ensure that the pokeys_py component meets real-time operation requirements. To run the performance tests, execute the following command:

pytest test_performance.py

Interpreting Test Results

After running the tests, pytest will display the test results in the terminal. The results will indicate the number of tests passed, failed, or skipped. Additionally, you can generate a coverage report to identify untested code.

To generate a coverage report, use the following command:

pytest --cov=pokeys_py --cov-report=html

The coverage report will be generated in the htmlcov directory. Open the index.html file in a web browser to view the detailed coverage report.

Hardware-Dependent Tests

Some tests may require physical hardware to run. For hardware-dependent tests, make sure the PoKeys device is connected and properly configured. Follow the setup steps provided in the documentation to ensure the hardware is ready for testing.

Continuous Integration (CI)

To integrate the tests into an automated testing pipeline, set up continuous integration (CI) to run the tests on every commit or pull request. This ensures that the code is continuously tested and any issues are detected early in the development process.

Running Tests with Mocks or Simulators

To run tests with mocks or simulators, follow these steps:

  1. Set the environment variable CI to true to enable the use of mocks in the CI environment.
  2. Run the tests as usual using pytest.

For example:

export CI=true
pytest test_analog_io.py
pytest test_counter.py
pytest test_digital_io.py
pytest test_pev2_motion_control.py
pytest test_ponet.py
pytest test_pwm.py
pytest test_integration.py
pytest test_functional.py
pytest test_performance.py

Setting Environment Variables

To toggle between real and mock devices, set the CI environment variable accordingly:

unset CI
# or
export CI=false
export CI=true

Documentation

The documentation provides clear instructions on running tests, setup steps for hardware-dependent tests, and interpreting test results and coverage reports. It is essential to keep the documentation up to date as new features are implemented and tests are added.

By following these instructions, you can ensure the reliability, correctness, and performance of the pokeys_py component, making it easier to maintain and develop in the future.

Configuring GitHub Actions Runners

To ensure that the CI workflow runs smoothly, it is important to configure GitHub Actions runners properly. This section provides instructions for setting up self-hosted runners and verifying the required permissions and access for runners.

Setting Up Self-Hosted Runners

  1. Create a Runner: Follow the instructions in the GitHub documentation to create a self-hosted runner. You can find the documentation here.

  2. Install the Runner: Download and install the runner on your machine. Make sure to follow the installation steps provided in the documentation.

  3. Configure the Runner: Configure the runner by running the config.sh script. Provide the necessary details such as the repository URL, runner name, and labels.

  4. Start the Runner: Start the runner by running the run.sh script. The runner should now be online and ready to pick up jobs.

Verifying Permissions and Access

  1. Repository Access: Ensure that the runner has access to the repository. This can be done by adding the runner to the repository settings under the "Actions" tab.

  2. Permissions: Verify that the runner has the necessary permissions to access the repository. This includes read and write permissions for the repository.

  3. Runner Logs: Check the runner logs for any errors or issues that might be preventing the job from being picked up. The logs can be found in the runner/logs directory.

  4. Self-Hosted Runners: If using self-hosted runners, ensure they are online and properly configured. This includes verifying the network connectivity and ensuring that the runner is not blocked by any firewall or security settings.

  5. GitHub-Hosted Runners: If using GitHub-hosted runners, verify that there are no restrictions or limitations on the number of concurrent jobs. This can be done by checking the GitHub Actions settings in the repository.

By following these steps, you can ensure that the GitHub Actions runners are properly configured and have the necessary permissions and access to run the CI workflow successfully.

Code Review Guidelines

Code reviews are an essential part of our development process. They help ensure code quality, maintainability, and foster collaboration within the team. The following guidelines outline the expectations for code reviews:

  1. Code Style: Adhere to the project's coding standards and style guidelines. Consistent code style makes the codebase easier to read and maintain.
  2. Documentation: Ensure that code is well-documented. This includes inline comments, function/method documentation, and any necessary external documentation.
  3. Testing: Verify that the code includes appropriate tests. This includes unit tests, integration tests, and any other relevant tests.
  4. Performance: Consider the performance implications of the code. Ensure that the code is efficient and does not introduce unnecessary performance bottlenecks.
  5. Security: Review the code for potential security vulnerabilities. Ensure that the code follows best practices for security.

For detailed guidelines, please refer to the Code Review Guidelines.

Contributing

We welcome contributions from the community to help improve the project. Please take a moment to review the CONTRIBUTING.md file for guidelines on how to contribute.

License

This project is licensed under the MIT License. See the LICENSE file for more details.

Branch Naming Conventions

To keep the repository organized, please follow these branch naming conventions:

Creating Separate Branches for Each Feature or Bug Fix

Each new feature or bug fix should have its own branch created from the latest version of the main branch. The branch should focus on one feature or issue to ensure isolated development.

Conformity with LinuxCNC Guidelines and Canonical Device Interface

This repository aligns with LinuxCNC’s development practices and canonical interfaces. The components have been reviewed and updated to follow LinuxCNC coding guidelines, ensuring that HAL and INI files conform to LinuxCNC’s structure and formatting. Real-time components comply with LinuxCNC’s real-time constraints, and all components follow the canonical interface definitions. The code adheres to LinuxCNC's code style and formatting guidelines, and test cases have been created and run to validate conformity.

Using Docker for Testing

To simplify the testing process and ensure consistency across different environments, we have integrated Docker into our testing workflow. This allows you to run tests inside a Docker container, providing an isolated and reproducible environment.

Building the Docker Image

To build the Docker image for testing, follow these steps:

  1. Ensure you have Docker installed on your machine. You can download and install Docker from here.

  2. Clone the repository and navigate to the project directory:

git clone https://github.com/zarfld/LinuxCnc_PokeysLibComp.git
cd LinuxCnc_PokeysLibComp
  1. Build the Docker image using the provided Dockerfile:
docker build -t linuxcnc-pokeyslibcomp .

Running Tests Inside the Docker Container

Once the Docker image is built, you can run tests inside the Docker container. This ensures that tests are executed in a consistent environment, regardless of the host system.

To run tests inside the Docker container, use the following command:

docker run --rm linuxcnc-pokeyslibcomp

This command will start a Docker container from the linuxcnc-pokeyslibcomp image and execute the tests inside the container. The --rm flag ensures that the container is removed after the tests are completed.

Benefits of Using Docker for Testing

By using Docker for testing, you can ensure that tests are executed in a consistent and isolated environment, reducing the chances of environment-related issues and making it easier to reproduce and debug test failures.

Using the create_images.sh Script

The create_images.sh script automates the build and image creation process for Raspberry Pi 4 Bullseye, Bookworm, and amd64 hybrid. Follow these steps to use the script:

  1. Ensure you have the necessary dependencies installed for cross-compiling for ARM and natively compiling for amd64.

  2. Run the create_images.sh script:

chmod +x create_images.sh
./create_images.sh

The script will build and create images for Raspberry Pi 4 Bullseye, Bookworm, and amd64 hybrid, following the structure and format of existing LinuxCNC releases. It will also test and validate the generated images.

Downloading Generated Images

The generated images are stored in the repository's releases or a suitable cloud storage platform. You can download the images from the following links:

Note on GitHub Actions Workflow

In the GitHub Actions workflow file, ensure that the runs-on key is correctly specified. The correct syntax for the runs-on key should be runs-on: ${{ matrix.os }} instead of runs-on: [self-hosted, ${{ matrix.os }}].

Supported Platforms and LinuxCNC Versions

The following platforms and LinuxCNC versions are supported:

Replicating CI Environments Locally

To replicate the CI environments locally, follow these steps:

  1. Clone the Repository:

    git clone https://github.com/zarfld/LinuxCnc_PokeysLibComp.git
cd LinuxCnc_PokeysLibComp

  2. Set Up the Environment:

    • Install the necessary dependencies: 
      sudo apt-get update
sudo apt-get install -y qemu qemu-user-static debootstrap

  3. Run the CI Pipeline Locally:

    • Execute the CI pipeline script: 
      ./create_images.sh

  4. Test and Validate the Generated Images:

    • Use QEMU to test and validate the generated images: 
      sudo qemu-system-aarch64 -M raspi3 -kernel rpi4_bullseye/boot/vmlinuz-*-arm64 -initrd rpi4_bullseye/boot/initrd.img-*-arm64 -append "root=/dev/sda2" -hda rpi4_bullseye.img -nographic

By following these steps, you can replicate the CI environments locally and ensure that the generated images are functioning correctly.

Labels for Issues and Pull Requests

To make it easier for new contributors to get started, we use specific labels to identify issues and pull requests that are suitable for beginners. These labels help contributors find tasks that match their experience level and ensure a smooth onboarding process.

Labels

Using Labels

When creating or reviewing issues and pull requests, apply the appropriate labels to help new contributors find suitable tasks. Here are some guidelines:

Encouraging New Contributors

We encourage new contributors to look for issues with these labels. If you are a first-time contributor, start by exploring the issues labeled good first issue, beginner friendly, or documentation. These tasks are designed to help you get started with the project and build your confidence as a contributor.

CI Job for Labeling Issues

Overview

A new CI job has been added to automatically review issues in the repository that are not yet labeled and assign the correct label based on the issue content. This helps maintainers and contributors identify tasks efficiently.

Configuration

The CI job is configured using GitHub Actions. The workflow file is named label_issues.yml and is located in the .github/workflows/ directory.

Triggering the CI Job

The CI job is triggered automatically in the following scenarios:

Label Assignment

The CI job uses a Python script named label_issues.py to analyze the issue content and assign labels based on keywords or an NLP model. The script uses the requests library to interact with the GitHub API.

Confidence Threshold

The CI job implements a confidence threshold to avoid incorrect labeling. If the confidence level is high (e.g., over 80%), the label is applied automatically. If the confidence level is low, the issue is flagged for manual review by maintainers with a comment like:

"This issue could not be confidently labeled. Please review manually."

Manual Override

Maintainers can manually override the label if the CI job incorrectly assigns one. The CI job also applies a needs-review label for issues where it is unsure about the appropriate label.

Excluding Issues with Existing Labels

The CI job excludes issues that already have one or more labels. It does not remove or change existing labels unless flagged by a maintainer.

Logging and Reporting

The CI job logs its actions, such as which issues were labeled and which issues it flagged for manual review. Optionally, it can send a daily or weekly report summarizing its actions to maintainers.

Error Handling

In case the CI job fails or cannot process an issue (e.g., due to parsing errors), it flags the issue with a needs-review label and provides a log or error report.

Examples of Automatically Assigned Labels

The following are examples of labels that can be automatically assigned by the CI job based on issue content:

By implementing this CI job, the repository ensures that issues are well-organized and labeled appropriately, improving issue management and making it easier for contributors to navigate the repository.

Swapping Between Real and Mocked pokeyslib

To facilitate testing and development, you can easily swap between the real pokeyslib and the mocked pokeyslib. This allows you to run tests without the need for physical PoKeys devices.

Using the Mocked pokeyslib

  1. Set the Environment Variable: Set the CI environment variable to true to enable the use of the mocked pokeyslib.
export CI=true
  1. Run the Tests: Execute the tests as usual using pytest.
pytest test_analog_io.py
pytest test_counter.py
pytest test_digital_io.py
pytest test_pev2_motion_control.py
pytest test_ponet.py
pytest test_pwm.py
pytest test_integration.py
pytest test_functional.py
pytest test_performance.py

Using the Real pokeyslib

  1. Unset the Environment Variable: Unset the CI environment variable or set it to false to use the real pokeyslib.
unset CI
# or
export CI=false
  1. Run the Tests: Execute the tests as usual using pytest.
pytest test_analog_io.py
pytest test_counter.py
pytest test_digital_io.py
pytest test_pev2_motion_control.py
pytest test_ponet.py
pytest test_pwm.py
pytest test_integration.py
pytest test_functional.py
pytest test_performance.py

Example Test Configuration

Here is an example of how to configure and run tests with the mocked pokeyslib:

export CI=true
pytest test_counter.py

This will run the test_counter.py tests using the mocked pokeyslib, allowing you to validate the behavior of the pokeys_py component without the need for physical hardware.

By following these instructions, you can easily swap between the real and mocked pokeyslib, enabling comprehensive testing and development of the pokeys_py component.

Mocked pokeyslib Design

1. Function Mocks

Each function provided by the real pokeyslib will have a mocked version with the exact same signature. The mocked function will simulate the expected hardware behavior.

Real pokeyslib.h:

POKEYSDECL int32_t PK_DigitalIOGet(sPoKeysDevice* device, uint8_t pinID, uint8_t* pinValue);

Mocked Version:

int32_t PK_DigitalIOGet(sPoKeysDevice* device, uint8_t pinID, uint8_t* pinValue) {
    *pinValue = 1;  // Simulate the pin being high
    return PK_OK;
}

All other functions in the library, such as PK_DigitalIOSet, PK_AnalogIOGet, PK_PEv2_PulseEngineMove, etc., will follow the same approach, mimicking the real behavior of the functions.

2. Structures and Enums

All the structures and enums defined in the original pokeyslib.h need to be replicated exactly in the mock to ensure binary compatibility when linking against components.

Real pokeyslib.h:

typedef struct sPoKeysDevice_Info {
    char deviceName[32];
    uint32_t serialNumber;
    uint88 firmwareVersionMajor;
    uint8_t firmwareVersionMinor;
    uint8_t numberOfPins;
} sPoKeysDevice_Info;

Mocked pokeyslib.h (identical to the real header):

typedef struct sPoKeysDevice_Info {
    char deviceName[32];
    uint32_t serialNumber;
    uint88 firmwareVersionMajor;
    uint8_t firmwareVersionMinor;
    uint8_t numberOfPins;
} sPoKeysDevice_Info;

3. State Management

The mocked library will maintain internal state to simulate real device behavior across function calls. This is particularly important for functions like PK_DigitalIOSet and PK_DigitalIOGet, where setting an output pin should affect subsequent input reads.

4. Configuration and Setup

The mock library must allow for custom configuration of the device state prior to tests. This includes setting up the initial state of pins, analog values, and other peripheral settings.

void setup_mock_device() {
    device_state.pins[0] = 1;  // Simulate pin 0 being high
    device_state.pins[1] = 0;  // Simulate pin 1 being low
}

Mock Library Integration

  1. Linking the Mock Library:

    • During testing, the mocked pokeyslib will be linked into the test environment.
    • During production builds, the real pokeyslib will be linked.

    CMake Example:

    if(BUILD_TESTS)
    target_link_libraries(my_tests PRIVATE mocked_pokeyslib)
else()
    target_link_libraries(my_project PRIVATE real_pokeyslib)
endif()

  2. Replacing the Real Library:

    • The CI pipeline or build system will determine whether to link against the real or mocked version of pokeyslib.

Testing with the Mock

TEST(MockPoKeysTest, TestDigitalIO) {
    sPoKeysDevice* device = CreateMockDevice();
    uint8_t pinValue = 0;

    PK_DigitalIOGet(device, 0, &pinValue);
    ASSERT_EQ(pinValue, 1);  // Check that the mock returns the expected value
}

Steps for Implementation

  1. Identify all Functions and Structures:

    • Review pokeyslib.h to identify all the functions, structures, and enums that need to be mocked.

  2. Implement Mocked Functions:

    • Implement each function in the mock library, ensuring that the signature matches the original.

  3. State Management:

    • Implement internal state management for pins, counters, PWM, and other device settings to simulate real device behavior.

  4. Testing:

    • Write unit tests that validate the mock by simulating real-world scenarios and comparing the mock behavior with expected outcomes.

  5. Documentation:

    • Provide clear documentation on how to swap between the real and mocked pokeyslib for testing and production.

Conclusion

This mocked pokeyslib will allow for full unit testing and CI pipeline testing without the need for physical devices. By maintaining the same interface as the real library, no changes to existing components will be necessary, ensuring seamless integration.

Wiki

We have a comprehensive Wiki to help you get started with the project and find detailed documentation. The Wiki is structured and organized according to best practices, making it easy to navigate and find the information you need.

Key Sections

Contributing to the Wiki

We encourage contributions to the Wiki to keep it up to date and comprehensive. If you would like to contribute to the Wiki, please follow these guidelines:

  1. Fork the Repository: Start by forking the repository to your GitHub account.
  2. Clone the Repository: Clone the forked repository to your local machine. 
    git clone https://github.com/your-username/LinuxCnc_PokeysLibComp.git
cd LinuxCnc_PokeysLibComp
  3. Create a Branch: Create a new branch for your Wiki contribution. 
    git checkout -b wiki/your-wiki-contribution
  4. Make Changes: Make your changes to the Wiki pages.
  5. Commit Changes: Commit your changes with a descriptive commit message. 
    git add .
git commit -m "Update Wiki: your contribution description"
  6. Push Changes: Push your changes to your forked repository. 
    git push origin wiki/your-wiki-contribution
  7. Create a Pull Request: Open a pull request from your forked repository to the main repository.

By following these steps, you can contribute to the Wiki and help improve the documentation for the project.

PoKeys Device Compatibility

PoKeys Device Supported Versions Notes
PoKeys57E 4.0, 4.1, 4.2 Limited support
PoKeys57CNC 3.5, 3.6, 3.7 Limited support
PoKeys57U 2.8, 2.9 Limited support
PoKeys56U 1.5, 1.6 Limited support

LinuxCNC Compatibility

The following table outlines the compatibility between different versions of LinuxCNC and the LinuxCnc_PokeysLibComp project:

LinuxCNC Version Supported Notes
2.8.x Yes Limited support
2.9.x Yes Limited support
2.7.x No Not supported nothing of them is Fully supported yet. this sis still in development no approval of support done!

GitHub Discussions

We encourage the use of GitHub Discussions for questions, feature requests, and ideas before creating issues or pull requests. This helps keep the issue tracker focused on actionable items and fosters community engagement.

Available Categories

We have created the following categories in GitHub Discussions to help organize conversations:

Guidelines for Starting a Discussion

When starting a discussion, please follow these guidelines:

  1. Choose the Appropriate Category: Select the category that best fits your topic to help keep discussions organized.
  2. Provide a Clear Title: Use a clear and descriptive title for your discussion.
  3. Include Relevant Details: Provide as much relevant information as possible to help others understand your question, idea, or request.
  4. Be Respectful and Constructive: Follow the project's Code of Conduct and engage in respectful and constructive conversations.

When to Use Discussions Instead of Issues or Pull Requests

Use GitHub Discussions for:

By using GitHub Discussions effectively, we can build a stronger community around the project and make the repository more welcoming to both new and experienced users.

You can access the GitHub Discussions for this repository here.

Sponsorship

We appreciate your interest in supporting the LinuxCnc_PokeysLibComp project! Your sponsorship helps us continue to develop and maintain this project. Here are some ways you can sponsor us:

For more detailed information on sponsorship tiers and benefits, as well as instructions on how to sponsor through GitHub Sponsors and PayPal, please refer to our Sponsorship Page.

Thank you for your support!

Setting Up Two-Factor Authentication (2FA) for GitHub Repositories

To set up two-factor authentication (2FA) for GitHub repositories, follow these steps:

Enable 2FA for Your GitHub Account

  1. Go to your GitHub account settings.
  2. Navigate to the "Security" section.
  3. Click on "Enable two-factor authentication".
  4. Follow the prompts to set up 2FA using either a mobile app or SMS.

Require 2FA for All Collaborators

  1. Go to the repository's settings.
  2. Navigate to the "Manage access" section.
  3. Click on "Require two-factor authentication for all collaborators".
  4. Confirm the changes.

Verify 2FA Setup

  1. Ensure that all collaborators have enabled 2FA on their GitHub accounts.
  2. Check the repository's access settings to confirm that 2FA is required for all collaborators.

By following these steps, you can enhance the security of your GitHub repository by requiring two-factor authentication for all collaborators. For more detailed instructions, refer to the GitHub documentation on setting up 2FA.

Enabling Dependabot Security Alerts and Automatic Updates

To enable Dependabot security alerts and automatic updates for your GitHub repository, follow these steps:

  1. Go to the repository's settings.
  2. Navigate to the "Security & analysis" section.
  3. Enable "Dependabot alerts" and "Dependabot security updates".

Dependabot will now monitor your repository for security vulnerabilities and automatically create pull requests to update dependencies when vulnerabilities are found.

Setting Up CodeQL for Code Scanning

To set up CodeQL for code scanning in your GitHub repository, follow these steps:

  1. Go to the repository's settings.
  2. Navigate to the "Security & analysis" section.
  3. Enable "Code scanning" and select "CodeQL" as the analysis tool.
  4. Configure the CodeQL workflow to run on push and pull request events.

CodeQL will now analyze your code for security vulnerabilities and provide detailed reports on potential issues.

Enabling Secret Scanning

To enable secret scanning for your GitHub repository, follow these steps:

  1. Go to the repository's settings.
  2. Navigate to the "Security & analysis" section.
  3. Enable "Secret scanning".

Secret scanning will now monitor your repository for exposed secrets, such as API keys and passwords, and alert you if any are found.

Limiting Access Control and Enforcing Least Privilege

To limit access control and enforce the principle of least privilege for your GitHub repository, follow these steps:

  1. Go to the repository's settings.
  2. Navigate to the "Manage access" section.
  3. Review the permissions of all collaborators and teams.
  4. Assign the minimum necessary permissions to each collaborator and team based on their role and responsibilities.
  5. Regularly review and update permissions to ensure they remain appropriate.

By limiting access control and enforcing least privilege, you can reduce the risk of unauthorized access and protect your repository from potential security threats.

Canonical Device Interface

The Canonical Device Interface (CDI) is a standardized interface for interacting with PoKeys devices in the LinuxCnc_PokeysLibComp project. It provides a consistent and unified way to access and control various features of PoKeys devices, ensuring compatibility and ease of use.

Features

The CDI supports the following features:

Usage Examples

Digital Input and Output

To read the state of a digital input pin and write a value to a digital output pin using the CDI, follow these examples:

import pokeys_py

# Initialize the PoKeys device
device = pokeys_py.PoKeysDevice()

# Read the state of digital input pin 0
pin_value = device.digital_read(0)
print(f"Digital input pin 0 state: {pin_value}")

# Set the state of digital output pin 0 to high
device.digital_write(0, 1)
print("Digital output pin 0 set to high")

Analog Input and Output

To read the value of an analog input pin and write a value to an analog output pin using the CDI, follow these examples:

import pokeys_py

# Initialize the PoKeys device
device = pokeys_py.PoKeysDevice()

# Read the value of analog input pin 0
analog_value = device.analog_read(0)
print(f"Analog input pin 0 value: {analog_value}")

# Set the value of analog output pin 0 to 2.5V
device.analog_write(0, 2.5)
print("Analog output pin 0 set to 2.5V")

Pulse Engine (PEv2)

To configure the Pulse Engine (PEv2) for motion control and move an axis using the CDI, follow these examples:

import pokeys_py

# Initialize the PoKeys device
device = pokeys_py.PoKeysDevice()

# Configure the Pulse Engine for axis 0
device.pev2_configure_axis(0, steps_per_unit=200, max_velocity=1000, acceleration=500)
print("Pulse Engine axis 0 configured")

# Move axis 0 to position 10.0
device.pev2_move_axis(0, 10.0)
print("Axis 0 moved to position 10.0")

Matrix Keyboard

To read the state of a matrix keyboard using the CDI, follow this example:

import pokeys_py

# Initialize the PoKeys device
device = pokeys_py.PoKeysDevice()

# Read the state of the matrix keyboard
key_state = device.matrix_keyboard_read()
print(f"Matrix keyboard state: {key_state}")

CNC Keyboard (PoNETkbd48CNC)

To set the state of an LED and read the state of a button on the CNC keyboard using the CDI, follow these examples:

import pokeys_py

# Initialize the PoKeys device
device = pokeys_py.PoKeysDevice()

# Set the state of LED 0 to on
device.kbd48CNC_set_led(0, 1)
print("LED 0 on the CNC keyboard set to on")

# Read the state of button 0 on the CNC keyboard
button_state = device.kbd48CNC_get_button(0)
print(f"Button 0 on the CNC keyboard state: {button_state}")

Encoder

To read the value of an encoder using the CDI, follow this example:

import pokeys_py

# Initialize the PoKeys device
device = pokeys_py.PoKeysDevice()

# Read the value of encoder 0
encoder_value = device.encoder_read(0)
print(f"Encoder 0 value: {encoder_value}")

Real-Time Clock

To read the real-time clock values using the CDI, follow this example:

import pokeys_py

# Initialize the PoKeys device
device = pokeys_py.PoKeysDevice()

# Read the real-time clock values
rtc_values = device.rtc_read()
print(f"RTC values: {rtc_values}")

Configuration Steps

To configure the CDI for use with PoKeys devices in LinuxCNC, follow these steps:

  1. Connect the Hardware: Ensure that the PoKeys devices are properly connected to your system according to the hardware requirements.

  2. Update LinuxCNC Configuration Files: Update the LinuxCNC configuration files to include the PoKeys components. Refer to the following example configuration:

[HAL]
# Load PoKeys HAL component
loadrt pokeys

# Add PoKeys device
addf pokeys.0 servo-thread

# Configure digital inputs and outputs
net input-0 <= pokeys.0.digin.0.in
net output-1 => pokeys.0.digout.1.out

# Configure analog inputs and outputs
net analog-input-0 <= pokeys.0.adcin.0.value
net analog-output-1 => pokeys.0.adcout.1.value
  1. Verify Connections: Ensure that the PoKeys devices are properly connected and recognized by LinuxCNC. Use the halcmd command to monitor the state of the inputs and outputs.

By following these steps and examples, you can effectively use the Canonical Device Interface to interact with PoKeys devices in the LinuxCnc_PokeysLibComp project.

Documentation

For detailed instructions on converting existing LinuxCNC HAL and INI files for use with pokeys.comp, pokeys_homecomp.comp, and kbd48cnc.comp, refer to the Converting HAL and INI Files documentation.