From 6d69c835a77dec4416fc18d15bb2be547f6c6531 Mon Sep 17 00:00:00 2001 From: Thomas Watson Date: Sun, 7 Jul 2024 11:35:35 -0500 Subject: [PATCH] common-lua-scripts: update serial binding docs Includes new `readstring` and `writestring` methods, as well as new serial device simulation support. --- common/source/docs/common-lua-scripts.rst | 27 +++++++++++++++++------ 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/common/source/docs/common-lua-scripts.rst b/common/source/docs/common-lua-scripts.rst index 1f87e0efd7..d70ef77b7f 100644 --- a/common/source/docs/common-lua-scripts.rst +++ b/common/source/docs/common-lua-scripts.rst @@ -467,17 +467,30 @@ RC Channels (rc:) - :code:`get_pwm()` - Returns the RC input PWM value given a channel number. Note that channel here is indexed from 1. Returns false if channel is not available. -Serial/UART (serial:) +Serial (serial:) ~~~~~~~~~~~~~~~~~~~~~ -- :code:`find_serial(instance)` - Returns the UART instance that allows connections from scripts (those with :code:`SERIALx_PROTOCOL = 28`). For :code:`instance = 0`, returns first such UART, second for :code:`instance = 1`, and so on. If such an instance is not found, returns :code:`nil`. +The serial library provides access to ArduPilot's serial port infrastructure and associated devices and drivers. The script can communicate with a device attached to the autopilot using the ``find_serial(instance)`` function. The script can also itself simulate being a device attached to the autopilot using the ``find_simulated_device(protocol, instance)`` function and ``SCR_SDEV*`` parameters. - - :code:`UART:begin(baud)` - Start serial connection at given baud rate. - - :code:`UART:read()` - Returns a sequence of bytes from UART instance. - - :code:`UART:write(number)` - Writes a sequence of bytes to UART instance. - - :code:`UART:available()` - Returns integer of currently available bytes. - - :code:`UART:set_flow_control(flow_control)` - Sets flow control for UART instance. +- ``find_serial(instance)`` - Returns a serial access object that allows a script to interface with a device over a port set to protocol 28 (Scripting) (e.g. ``SERIALx_PROTOCOL``, though CAN/NET/etc ports work as well). Instance 0 is the first such port, instance 1 the second, and so on. If the requested instance is not found, returns ``nil``. +- ``find_simulated_device(protocol, instance)`` - Returns a serial access object that allows a script to simulate a device attached via a specific protocol. The device protocol is configured by the parameter ``SCR_SDEVx_PROTO``. Instance 0 is the first such protocol, instance 1 the second, and so on. If the requested instance is not found, or the parameter ``SCR_SDEV_EN`` is disabled, returns ``nil``. + +The objects returned by the above functions support the following methods: + +- ``port:begin(baud_rate)`` - Start communication at the given baud rate. Must be called to initialize scripting protocol ports (those from ``find_serial``). No effect for device simulation ports (those from ``find_simulated_device``). + +- ``port:write(value)`` - Write a single byte. Returns 1 if successful, or 0 if failed (i.e. buffer space full). + +- ``port:writestring(data)`` - Write a string. The number of bytes actually written, i.e. the length of the written prefix of the string, is returned. It may be 0 up to the length of the string. + +- ``port:read()`` - Read a single byte. Returns the byte if successful, or -1 if failed (i.e. none available or some other error). + +- ``port:readstring(count)`` - Read up to ``count`` bytes and return the bytes read as a string. No bytes may be read, in which case a 0-length string is returned. If there is an error, ``nil`` is returned. + +- ``port:available()`` - Returns the number of bytes available to read. A read of the given number of bytes may fail on certain errors or if there is another reader (e.g. mavlink passthrough), though these are extremely unlikely occurrences. + +- ``port:set_flow_control(fcs)`` - Set flow control setting for scripting protocol ports (those from ``find_serial``). No effect for device simulation ports (those from ``find_simulated_device``). ``fcs`` can be 0 to disable, 1 to enable, or 2 for automatic mode. Barometer (baro:) ~~~~~~~~~~~~~~~~~