view release on metacpan or  search on metacpan

lib/RPi/Serial.pm  view on Meta::CPAN

    my $dev  = "/dev/ttyAMA0";
    my $baud = 115200;
    
    my $ser = RPi::Serial->new($dev, $baud);

    # Write a single char

    $ser->putc(5);

    # Write a string

    $ser->puts("hello, world!");

    # Write a single byte by its integer value (0-255)

    $ser->write(65);
    my $char = $ser->getc;

    # Get a string

    my $num_bytes = 12;
    my $str  = $ser->gets($num_bytes);

    # Send a CRC-framed payload between start/end delimiters

    $ser->tx("payload", "<", ">");

    # Receive a CRC-framed payload (call in a loop until it returns the data)

    my $frame = $ser->rx("<", ">");

    my $crc = $ser->crc($str);

    $ser->flush;

    my $bytes_available = $ser->avail;

    $ser->close;

=head1 DESCRIPTION

Provides basic read and write functionality of a UART serial interface

=head1 WARNING

If using on a Raspberry Pi platform, the procedure to enable GPIO pins 14 (TXD)
and 15 (RXD) as a serial interface differs by board. On B<all> boards, first
free the port from the kernel console: in C<raspi-config>, under C<Interface
Options -E<gt> Serial Port>, answer B<no> to the login shell and B<yes> to the
serial hardware.

=head2 Raspberry Pi 3 / 4 (and Zero W)

The on-board Bluetooth modem is wired to the primary PL011 UART, leaving GPIO
14/15 on the inferior, baud-unstable mini-UART (C</dev/ttyS0>). To move the good
UART onto the header pins you must disable Bluetooth. Edit
C</boot/firmware/config.txt> (C</boot/config.txt> on releases before Bookworm)
and add:

    enable_uart=1
    dtoverlay=disable-bt

With that overlay the header serial port becomes C</dev/ttyAMA0>.

=head2 Raspberry Pi 5

Bluetooth has its B<own dedicated UART> and is B<not> shared with the GPIO 14/15
pins, so there is nothing to disable. Just enable the header UART in
C</boot/firmware/config.txt>:

    enable_uart=1

The header serial port is C</dev/ttyAMA0>. (Note that on the Pi 5
C</dev/serial0> maps to the separate 3-pin debug-UART connector, B<not> the
header pins.)

Save the file, then reboot the Pi.

=head1 METHODS

=head2 new($device, $baud);

Opens the specified serial port at the specified baud rate, and returns a new
L<RPi::Serial> object.

Parameters:

    $device

Mandatory, String: The serial device to open (eg: C<"/dev/ttyAMA0">).

    $baud

Mandatory, Integer: A valid baud rate to use.

=head2 close

Closes an already open serial device.

=head2 avail

Returns the number of bytes waiting to be read if any.

=head2 flush

Flush any data currently in the serial buffer.

=head2 fd

Returns the C<ioctl> file descriptor for the current serial object.

=head2 getc

Retrieve a single character from the serial port.

=head2 gets($num_bytes)

Read up to a specified number of bytes and return them as a string.

The read blocks only until the port's configured read timeout (the C<VTIME>
value set when the port was opened) elapses, so the returned string may be
B<shorter> than C<$num_bytes> if fewer bytes arrived in time (or the device
closed). The result is binary-safe: embedded C<NUL> bytes and trailing