Servo motor control by PWM

How does a PWM signal control a servo motor? A PWM signal consists of a series of pulses, where the width (duration) of each pulse determines the position of the servo motor. For example, a pulse width of 1 millisecond might correspond to the servo being at its minimum position, while a pulse width of 2 milliseconds might correspond to the servo being at its maximum position. By varying the pulse width between these two extremes, you can control the position of the servo motor with fairly high precision.

Inside the servo motor, there is a small circuit that interprets the PWM signal. The circuit uses the pulse width to determine how much to rotate the motor shaft. When the pulse width is short, the motor rotates to a position corresponding to that width. When the pulse width is long, it rotates to a different position. By continuously sending PWM signals with varying widths, a control system can move the servo motor to any desired position within its range. Of course, exactly which pulse width corresponds to which position depends on the servo’s physical characteristics and the mechanical setup within the robotic arm: its mounting and link geometry, friction, and load conditions.

Linux Kernel configuration

The Linux kernel needs to be configured to support the PCA9685(A) I²C PWM controller. The “A” suffix indicates the A-step variant of the chip. Configuration is done by adding the following line to the device tree overlay configuration:

dtparam=i2c_arm=on

# Add support for an NXP PCA9685A I2C PWM controller.
dtoverlay=i2c-pwm-pca9685a

What does this do? It adds support for the PCA9685A I²C PWM controller to the Linux kernel, allowing the system to communicate with and control the PCA9685A chip via the I²C interface. This enables users to utilise the features of the PCA9685A, such as controlling LED brightness or driving servo motors, through software running on the device. The dtoverlay directive specifies a device tree overlay, a way to modify the kernel’s device tree at runtime.

How does it find the PCA9685A? The kernel will scan the I²C bus for the device and identify the PCA9685A based on its unique I²C address. Once detected, the kernel will load the corresponding driver, enabling communication and control of the PCA9685A chip through the I²C interface. This allows users to interact with the chip via software commands, such as setting PWM values to control LED brightness or controlling servo motors connected to the PCA9685A.

It’s worth noting that the dtoverlay command can be used with various parameters to specify the I²C address of the PCA9685A and other settings. For example, you can specify the I²C address using the addr parameter, and you can also select the I²C bus using standard I²C bus selection parameters. This flexibility allows for customisation based on your specific hardware setup and requirements.

$ dtoverlay -h i2c-pwm-pca9685a
Name:   i2c-pwm-pca9685a

Info:   Adds support for an NXP PCA9685A I2C PWM controller on i2c_arm

Usage:  dtoverlay=i2c-pwm-pca9685a,<param>=<val>

Params: addr                    I2C address of PCA9685A (default 0x40)
        i2c-bus                 Supports all the standard I2C bus selection
                                parameters - see "dtoverlay -h i2c-bus"

Reading as something

The following Prolog code defines a predicate read_file_as/2 that reads the contents of a file and converts it to a specified format based on the provided term. The term can specify different formats such as

• term(Term),
• bytes(Bytes),
• number(Number),
• atom(Atom),
• lines(Lines),
• line(Line),
• bigs(Width, Bigs),
• big(Width, Big),
• littles(Width, Littles),
• little(Width, Little).

The actual reading and conversion logic is implemented in the as/3 predicate, which is defined as a multifile predicate, allowing for extensibility with additional read methods in other modules. Each read method handles the reading and conversion of the file contents according to the specified format, providing a flexible way to read files in various formats as needed by the application.

read_file_as(File, Term) :-
    Term =.. [As, Data],
    !,
    as(As, File, Data).
read_file_as(File, Term) :-
    Term =.. [Name, Arg, Data],
    As =.. [Name, Arg],
    as(As, File, Data).

read_file_as(As, File, Data) :- as(As, File, Data).

% The as/3 predicate is defined as a multifile predicate, which allows it to be
% extended with additional read methods in other modules. Each read-as method is
% defined as a clause of the as/3 predicate, and the first argument specifies
% the name of the read method. The as/3 predicate is called by read_file_as/2 to
% perform the actual reading of the file based on the specified read method. The
% as/3 predicate is semidet, meaning that it will succeed if the file is read
% successfully according to the specified method, and fail otherwise. The as/3
% predicate is also deterministic, meaning that it will not leave a choice point
% after succeeding, as each read method is designed to read the file in a
% specific way and will not produce multiple results for the same file and
% method.
:- multifile as/3.

as(term, File, Data) :-
    as(line, File, Line),
    term_string(Data, Line).
as(bytes, File, Data) :-
    absolute_file_name(File, Abs, [file_errors(fail), access(read)]),
    read_file_to_codes(Abs, Data, [file_errors(fail), type(binary)]).
as(number, File, Data) :-
    as(line, File, Line),
    number_string(Data, Line).
as(atom, File, Data) :-
    as(line, File, Line),
    atom_string(Data, Line).
as(lines, File, Data) :-
    absolute_file_name(File, Abs, [file_errors(fail), access(read)]),
    read_file_to_string(Abs, String, [file_errors(fail)]),
    string_lines(String, Data).
as(line, File, Data) :-
    as(lines, File, [Data]).
as(bigs(Width), File, Data) :-
    as(bytes, File, Bytes),
    once(phrase(sequence(big_endian(Width), Data), Bytes)).
as(big(Width), File, Data) :-
    as(bigs(Width), File, [Data]).
as(littles(Width), File, Data) :-
    as(bytes, File, Bytes),
    once(phrase(sequence(little_endian(Width), Data), Bytes)).
as(little(Width), File, Data) :-
    as(littles(Width), File, [Data]).

The predicate requires that the file exists and is accessible for reading. If the file does not exist or cannot be read, the predicate will fail. The read_file:as/3 predicate handles the actual reading and conversion of the file contents based on the specified format, allowing for flexible and reusable file reading in Prolog applications.

sysfs_pwmchip_path(Chip, Path) :-
    sysfs_entry(pwm, Entry, [Chip, npwm]),
    (   var(Path)
    ->  file_directory_name(Entry, Path)
    ;   file_directory_name(Entry, Path),
        !
    ).

sysfs_pwmchip_read(What, Term) :-
    What =.. [Chip, File],
    sysfs_pwmchip_path(Chip, Path),
    read_file_as(Path/File, Term).

sysfs_pwmchip_read(File, Chip, Data) :-
    file_as(File, As),
    sysfs_pwmchip_path(Chip, Path),
    read_file_as(As, Path/File, Data).

file_as(npwm, number).
file_as(device/name, atom).

Writing as something

The following does the opposite of read_file_as/2. It defines a predicate write_file_as/2 that writes data to a file in a specified format based on the provided term. Similar to read_file_as/2, the term can specify different formats such as term(Term), bytes(Bytes), number(Number), atom(Atom), lines(Lines), line(Line), bigs(Width, Bigs), big(Width, Big), littles(Width, Littles), or little(Width, Little). The actual writing and conversion logic is implemented in the write_file:as/3 predicate, which is defined as a multifile predicate, allowing for extensibility with additional write methods in other modules. Each write method handles the conversion of the data to the specified format and writes it to the file accordingly, providing a flexible way to write files in various formats as needed by the application.

write_file_as(File, Term) :-
    Term =.. [As, Data],
    !,
    as(As, File, Data).
write_file_as(File, Term) :-
    Term =.. [Name, Arg, Data],
    As =.. [Name, Arg],
    as(As, File, Data).

write_file_as(As, File, Data) :- as(As, File, Data).

:- multifile as/3.

as(term, File, Data) :-
    term_string(Data, Line),
    as(line, File, Line).
as(bytes, File, Data) :-
    absolute_file_name(File, Abs, [file_errors(fail), access(write)]),
    write_bytes_to_file(Abs, Data, [file_errors(fail), type(binary)]).
as(number, File, Data) :-
    number_string(Data, Line),
    as(line, File, Line).
as(atom, File, Data) :-
    atom_string(Data, Line),
    as(line, File, Line).
as(lines, File, Data) :-
    string_lines(String, Data),
    absolute_file_name(File, Abs, [file_errors(fail), access(write)]),
    write_string_to_file(Abs, String, [file_errors(fail)]).
as(line, File, Data) :-
    as(lines, File, [Data]).
as(bigs(Width), File, Data) :-
    once(phrase(sequence(big_endian(Width), Data), Bytes)),
    as(bytes, File, Bytes).
as(big(Width), File, Data) :-
    as(bigs(Width), File, [Data]).
as(littles(Width), File, Data) :-
    once(phrase(sequence(little_endian(Width), Data), Bytes)),
    as(bytes, File, Bytes).
as(little(Width), File, Data) :-
    as(littles(Width), File, [Data]).

Together, these predicates provide a simple and flexible way to handle file I/O in Prolog, especially when dealing with the sysfs interface for device driver communication. By abstracting away the details of file handling and allowing for different data representations, they enable developers to easily read and write files in various formats as needed by their applications.

Export a PWM channel

Given a PCA9685 chip with a certain number of channels, you can export a specific channel using the following Prolog code:

sysfs_pwm_export(Chip, Export, Chan) :-
    sysfs_pwm_chan(Chip, Export, Chan),
    write_file_as(sysfs_class_pwm(Chip/export), number(Export)).

sysfs_pwm_chan(Chip, Export, Chan) :-
    sysfs_pwmchip_read(npwm, Chip, N),
    succ(N0, N),
    between(0, N0, Export),
    format(atom(Chan), 'pwm~d', [Export]).

The sysfs_pwm_export/3 predicate takes three arguments:

1. Chip, which identifies the PCA9685 chip;
2. Export, which is the channel number to be exported; and
3. Chan, which is the name of the channel that will be created in the sysfs interface.

The predicate first checks if the channel can be exported using sysfs_pwm_chan/3, which verifies that the specified channel number is within the valid range of channels available on the chip. If the channel can be exported, it writes the channel number to the export file in the sysfs interface, making it available for use.

Caveat: the export operation is not instantaneous. There is a delay between the time when the userland application requests an export and the appearance of the corresponding sysfs files. This is because the kernel needs to create the necessary directory and files in the sysfs interface for the exported channel, which can take some time. Therefore, after exporting a channel, it may be necessary to wait for a short period before the channel’s files become available for reading or writing. This delay can vary based on the system’s performance and the current load on the kernel, so it’s important to account for this when designing applications that interact with the sysfs interface for PWM control.

Ensuring exported channels are available

To ensure that the exported channels are available before attempting to read from or write to them, the application must implement a waiting mechanism that checks for the existence of the required sysfs files. This can be done using a loop that repeatedly checks for the presence of the channel’s directory and files in the sysfs interface, with a timeout to prevent infinite waiting. For example, the application can use a time limit to wait for the channel to become available, and if it does not become available within that time frame, it can handle the situation accordingly (e.g., by logging an error or retrying the export operation). This approach ensures that the application does not attempt to interact with channels that have not yet been fully exported and are not ready for use.

sysfs_pwm_read(File, Chip, Export, Data) :-
    file_as(File, As),
    sysfs_pwm_ensure_exported(Chip, Export, Chan),
    sysfs_exported_with_time_limit(sysfs_class_pwm(Chip/Chan/File), Abs, [access(read)]),
    read_file_as(As, Abs, Data).

:- setting(sysfs_exported_time_limit, number, 1,
           'Time limit for sysfs exported calls in seconds').
:- setting(sysfs_exported_delay_time, number, 0.01,
           'Delay time between sysfs exported call retries in seconds').

sysfs_exported_with_time_limit(File, Abs, Options) :-
    setting(sysfs_exported_time_limit, TimeLimit),
    setting(sysfs_exported_delay_time, DelayTime),
    call_with_time_limit(TimeLimit,
                         (   repeat,
                             absolute_file_name(File, Abs, [file_errors(fail)|Options])
                         ->  !
                         ;   sleep(DelayTime),
                             fail
                         )).

Note that the sysfs_pwm_read/4 predicate ensures that the specified channel is exported and available before attempting to read from the corresponding sysfs file. It uses the sysfs_exported_with_time_limit/3 predicate to wait for the channel’s files to become available, with a specified time limit and delay between retries. This approach helps to ensure that the application can reliably interact with the PWM channels without encountering errors due to unavailable sysfs files.

Checking needs to apply on a per-file basis, as the sysfs files for a channel may not all become available at the same time. For example, the duty_cycle file may become available before the period file, so the implementation checks for the availability of each required file before attempting to read from or write to it. This ensures that an application can easily handle the dynamic nature of the sysfs interface and avoid errors that may arise from trying to access files that have not yet been created by the kernel after exporting a channel.

This checking mechanism allows an application to safely interact with PWM channels in a robust and reliable manner, accounting for the potential delays in the availability of the sysfs files after exporting a channel.

Example usage

The following Prolog query demonstrates how to set the duty cycle for the elbow DOF to 30% with debugging enabled:

?- dof_duty_cycle(elbow, 0.3).
% Read string from file: /sys/class/pwm/pwmchip2/(device/name)
pca9685-pwm
--
% Read string from file: /sys/class/pwm/pwmchip2/npwm
17
--
% Read string from file: /sys/class/pwm/pwmchip2/npwm
17
--
% Read string from file: /sys/class/pwm/pwmchip2/pwm13/period
5079040
--
% Read string from file: /sys/class/pwm/pwmchip2/npwm
17
--
% Read string from file: /sys/class/pwm/pwmchip2/npwm
17
--
% Wrote string to file: /sys/class/pwm/pwmchip2/pwm13/duty_cycle
1523712
--
true.

The query calls the dof_duty_cycle/2 predicate for the elbow-specific DOF. Duty cycle for the elbow DOF becomes 30% (0.3) in this example. Prolog reads the pre-loaded period from the sysfs interface to determine the correct value to write to the duty_cycle file for the specified DOF. It computes the duty cycle from the PWM signal period and the desired duty cycle. The clamp/4 predicate ensures that the calculated duty cycle value is within the valid range of \([0, Period-1]\). Finally, the value is written to the duty_cycle file for the elbow DOF, effectively setting its position according to the specified duty cycle.

Of course, it does not instantly move to the 30% position. It takes some small amount of time: firstly, for the virtual file system to propagate the change to the duty_cycle file through the driver to the PCA9685; and secondly, for the servo motor to physically move to the new position based on the updated PWM signal. The actual time taken can vary depending on the specific hardware and the system’s current state.

Notice that there are two consecutive reads of the npwm file in the output. This is because the duty_cycle/3 predicate reads the period value from the sysfs interface, which involves reading the npwm file to determine the number of PWM channels available. The first read of npwm is to check the number of PWM channels, and the second read is to confirm that the number of channels has not changed before writing the new duty cycle value. This is a common pattern in Prolog backtracking, made apparent here when interacting with the external system, where multiple reads ensure the consistency and correctness of the data being processed. It could be optimised away by tabling, but that would assume the device does not change the number of channels; it does not, but the logic does not know that without additional knowledge. That could be additional future optimisation logic that memoises results based on known invariants.