luars232 API documentation

["David Collier" <myshkin@...>]

I am new to Lua, and I want to write stuff that talks to RS232 ports.

Initially on a PC, though eventually on Linux and eLua systems too.

I picked up an example which called up luars232, but couldn't find a
written API spec.

I have written my own, since our in-house standards require me to
document it, and it's good for my soul.
I'd appreciate it if anyone can see anything wrong with what I wrote ....

Is it of any use for adding to the overall project, and if so, where
might the text properly belong?

copy below

David

--[[
This program makes use of luars232, which is an implementation of
librs232, a C library.

There doesn't seem to be any documentation on what luars232 does,
but you can deduce it by looking at the example code here:

https://github.com/ynezz/librs232/blob/master/doc/example.lua

and the generic source code here:

https://github.com/ynezz/librs232/blob/master/src/rs232.c

and the lua source code here:

https://github.com/ynezz/librs232/blob/master/bindings/lua/luars232.c

                 My attempt at documentation for luars232

There are 2 functions - 
    open                  -- rs232Library = require("luars232")
-- error, port  = rs232Library.open(device) --
device can be "/dev/ttyUSB0" or "COM1"
    error_tostring

There are the following methods available once open() is successful. 
See lines in luars232.c following
  static luaL_reg port_methods[] 

  standard methods:
    __tostring            -- get string describing rs232 instance
    __gc                  -- synonym for close
    
    device                -- get device name?
    fd                    -- get file descriptor

read                  -- error, data, read_len =
port:read(max_read_len [ [, timeout_ms], forced])
--   if forced > 0 then read() blocks until
'timeout_ms' or there's 'max_read_len' bytes available
write                 -- error, written_len = port:write(data [,
timeout_ms])
    close                 -- error = port:close()
    flush                 -- error = port:flush()
        
set_baud_rate         -- needs a symbolic baud rate            like
luars232.RS232_BAUD_115200 as a parameter
set_data_bits         -- needs a symbolic number of data bits  like
luars232.RS232_DATA_8      as a parameter 
set_stop_bits         -- needs a symbolic number of stop bits  like
luars232.RS232_STOP_1      as a parameter 
set_parity            -- needs a symbolic parity setting       like
luars232.RS232_PARITY_NONE as a parameter 
set_flow_control      -- needs a symbolic flow control setting like
luars232.RS232_FLOW_OFF    as a parameter
set_dtr               -- needs a symbolic DTR setting          like
luars232.RS232_DTR_ON      as a parameter
set_rts               -- needs a symbolic RTD setting          like
luars232.RS232_RTS_ON      as a parameter

    baud_rate             -- get symbol for baud rate
baud_rate_tostring    -- converts a symbol like like
luars232.RS232_BAUD_115200 to a human-readable string
    
    data_bits             -- get symbol for number of data bits
dta_bits_tostring     -- converts a symbol like like
luars232.RS232_DATA_8 to a human-readable string
    
    stop_bits             -- get symbol for number of stop bits
stop_bits_tostring    -- converts a symbol like like
luars232.RS232_STOP_1 to a human-readable string
    
    parity                -- get symbol for parity setting
parity_tostring       -- converts a symbol like like
luars232.RS232_PARITY_NONE to a human-readable string
    
    flow_control          -- get symbol for flow control setting
flow_control_tostring -- converts a symbol like like
luars232.RS232_FLOW_OFF to a human-readable string
    
    dtr                   -- get symbol for DTR setting
dtr_tostring          -- converts a symbol like like
luars232.RS232_DTR_ON to a human-readable string
    
    rts                   -- get symbol for RTS setting
rts_tostring          -- converts a symbol like like
luars232.RS232_RTS_ON to a human-readable string


--]]