User Manual

User Manual:

Open the PDF directly: View PDF .
Page Count: 38

A Simple I/O Library for

Embedded Linux Systems

http://git.munts.com/libsimpleio

By Philip Munts

President, Munts AM Corp

Contents

Revision History.............................................................................................................2

Introduction....................................................................................................................3

Rationale...................................................................................................................................3

Copyright and Licensing...........................................................................................................3

Online Resources.....................................................................................................................4

Installation......................................................................................................................5

From Debian Package Repository...........................................................................................5

From Source Checkout.............................................................................................................5

Coding Conventions......................................................................................................7

Naming.....................................................................................................................................7

Argument Passing....................................................................................................................8

Language Bindings...................................................................................................................8

I/O Subsystem Overviews.............................................................................................9

libadc........................................................................................................................................9

libdac........................................................................................................................................9

libevent.....................................................................................................................................9

libgpio.....................................................................................................................................10

libhidraw..................................................................................................................................10

libi2c........................................................................................................................................10

liblinux.....................................................................................................................................11

liblinx.......................................................................................................................................11

libpwm.....................................................................................................................................12

libserial....................................................................................................................................12

libspi........................................................................................................................................12

libstream.................................................................................................................................13

libipv4......................................................................................................................................13

libwatchdog.............................................................................................................................14

Man Pages.....................................................................................................................15

A Simple I/O Library for Embedded Linux Systems – Revision 6, 4 February 2019 Page 1

Revision History

Revision 1, 9 August 2017 Initial draft.

Revision 2, 11 August 2017 Added revision history. Added installation instructions.

Added note that libsimpleio can be used with desktop

Linux. Added note that calling EVENT_wait() with zero

timeout can be used for polling without blocking.

Revision 3, 15 November 2017 Added libadc, which provides services for Linux Industrial

I/O Subsystem ADC (Analog to Digital Converter) inputs.

Upgraded from Debian Jessie to Stretch.

Revision 4, 12 May 2018 Switched from the old deprecated GPIO sysfs API to the new

GPIO descriptor API.

Revision 5, 14 May 2018 Header files are now installed to

/usr/local/include/libsimpleio.

Revision 6, 4 February 2019 Added libdac, which provides services for Linux Industrial

I/O Subsystem DAC (Digital to Analog Converter) outputs.

Renamed the repository for MuntsOS Embedded Linux

Framework from http://git.munts.com/arm-linux-mcu to

http://git.munts.com/muntsos.

A Simple I/O Library for Embedded Linux Systems – Revision 6, 4 February 2019 Page 2

Introduction

Rationale

libsimpleio is an attempt to regularize the mish-mash of API styles that Linux presents for

I/O device access. The support for I/O devices in Linux has evolved over time such that there

are many different and incompatible API styles. For example, an application program must

use ioctl() to access SPI (Serial Peripheral Interconnect) devices, tcsetattr() and other

functions defined in termios.h to access serial port devices, and Berkeley sockets library

functions to access network devices.

libsimpleio exports C functions with a common and highly regular calling sequence that

encapsulate and hide the underlying Linux system call services. These C functions are

callable from Ada, C#, Java, and Free Pascal application programs, using the native or

external library binding facility each language provides.

Although primarily intended for dedicated embedded Linux systems (such as MuntsOS

Embedded Linux), libsimpleio is also usable on mainstream desktop Linux systems such

as Debian or Ubuntu.

All original works in libsimpleio are copyrighted and licensed according the following 1-

clause BSD source code license:

Redistribution and use in source and binary forms, with or without

modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice,

this list of conditions and the following disclaimer.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"

AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE

LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR

CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF

SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS

INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN

CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)

ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE

POSSIBILITY OF SUCH DAMAGE.

A Simple I/O Library for Embedded Linux Systems – Revision 6, 4 February 2019 Page 3

Online Resources

The web site and git source code repository for libsimpleio is available at:

http://git.munts.com/libsimpleio

The man pages specifiying the API (Application Program Interface) for libsimpleio are

available for browsing at:

http://git.munts.com/libsimpleio/doc/libsimpleio.html

Prebuilt libsimpleio packages for Debian Stretch and compatible Linux operating systems

are available for download at:

http://repo.munts.com/debian9

The web site and git source code repository for the MuntsOS Embedded Linux Framework

is available at:

http://git.munts.com/muntsos

A Simple I/O Library for Embedded Linux Systems – Revision 6, 4 February 2019 Page 4

Installation

From Debian Package Repository

The easiest way to use libsimpleio on Debian Linux and its derivatives is to add the Munts

Technologies Debian Package Repository to your system, with the following commands:

wget http://repo.munts.com/debian9/PublicKey.txt

sudo apt-key add PublicKey.txt

wget http://repo.munts.com/debian9/amd64/munts-repo.deb

sudo dpkg -i munts-repo.deb

Then you can install the native libsimpleio package with these commands:

apt-get update

apt-get install munts-libsimpleio

The package installs files into several directories under the /usr/local directory tree:

/usr/local/include/libsimpleio

/usr/local/lib

/usr/local/libexec

/usr/local/share/libsimpleio

/usr/local/share/man

There are also cross-compiled packages for MuntsOS Embedded Linux available in the

repository. You can install them with the following commands:

apt-get update

apt-get install gcc-armv6-linux-gnueabihf-buildroot-libsimpleio

apt-get install gcc-armv7-linux-gnueabihf-buildroot-libsimpleio

From Source Checkout

Alternatively, or for non-Debian Linux distributions, libsimpleio can be built and installed

from a source checkout, with the following commands:

git clone http://git.munts.com/libsimpleio.git

cd libsimpleio

make

sudo make install

A Simple I/O Library for Embedded Linux Systems – Revision 6, 4 February 2019 Page 5

A Simple I/O Library for Embedded Linux Systems – Revision 6, 4 February 2019 Page 6

Coding Conventions

Naming

Each C function exported by libsimpleio is named according to the following convention:

<SUBSYSTEM>_<operation>()

where the prefix <SUBSYSTEM> indicates a particular I/O subsystem (I2C, SPI, watchdog timer,

etc.) and the suffix <operation> indicates a particular I/O operation (open, close, etc.). The

subsystem prefix is always spelled in all capital letters and the operation suffix is always

spelled in all lower case letters. Examples:

●GPIO_configure()

●I2C_transaction()

●WATCHDOG_open()

All C function declarations are bracketed between _BEGIN_STD_C and _END_STD_C macros

(defined in cplusplus.h) to prevent name mangling when a header file is included by a C++

source file.

Constants exported by libsimpleio, whether defined with #define or with typedef enum,

are always spelled with all capital letters. Examples:

●GPIO_DIRECTION_INPUT

●CMD_SPI_OPEN

Note: The language bindings do not necessarily adhere to the above naming conventions.

A Simple I/O Library for Embedded Linux Systems – Revision 6, 4 February 2019 Page 7

Argument Passing

All C functions exported by libsimpleio shall be proper procedures without any return

value.

All numeric and enumeration type arguments shall be defined as 32-bit signed integers

(int32_t), unless there is compelling reason otherwise. Each numeric argument shall be

passed by value (int32_t x). If a value is to be returned, a numeric or enumeration type

argument shall be passed by reference (int32_t *x). Example:

void GPIO_close(int32_t fd, int32_t *error);

All string arguments shall be NUL terminated C strings. Each string parameter shall be defined

with: const char *, or, if a value is to be returned: char *. Example:

LINUX_drop_privileges(const char *username, int32_t *error);

Language Bindings

Each language binding (available for Ada, C#, Java, and Pascal) shall consist only of type,

constant and function declarations that map each C type, constant or function declaration into

the target programming language.

For a particular I/O subsystem, all of the language bindings (e.g. libgpio.h, libgpio.ads,

libgpio.cs, libgpio.java, and libgpio.pas) shall be functionally identical.

A Simple I/O Library for Embedded Linux Systems – Revision 6, 4 February 2019 Page 8

I/O Subsystem Overviews

Please refer to the man pages (online at the links below, from the man command, or in the

appendix to this document) for the exact API specification for each subsystem.

libadc

http://git.munts.com/libsimpleio/doc/libadc.html

This library provides wrapper functions to read from Linux Industrial I/O Subsystem ADC

(Analog to Digital) Converters. Use ADC_open() to open an analog input device. Use

ADC_read() to sample an analog input.

Note: ADC_read() returns an analog sample as a right justified 32-bit integer. The meaning

of this integer (i.e. the ADC resolution) is system dependent.

libdac

http://git.munts.com/libsimpleio/doc/libdac.html

This library provides wrapper functions to write to Linux Industrial I/O Subsystem DAC (Digital

to Analog) Converters. Use DAC_open() to open an analog input device. Use DAC_write()

to write to an analog output.

Note: DAC_write() accepts an analog sample as a right justified 32-bit integer. The

meaning of this integer (i.e. the DAC resolution) is system dependent.

libevent

http://git.munts.com/libsimpleio/doc/libevent.html

This library provides wrapper functions for the Linux epoll I/O event notification system call

functions. Use EVENT_open() to create an event handler. Use EVENT_register() to

occurs.

Note: EVENT_wait() suspends the entire calling process (all threads).

Note: Passing a timeoutms value of zero to EVENT_wait() causes it to return immediately,

and can be used to poll the availablity of data without blocking at all.

A Simple I/O Library for Embedded Linux Systems – Revision 6, 4 February 2019 Page 9

libgpio

http://git.munts.com/libsimpleio/doc/libgpio.html

This library provides wrapper functions for the Linux GPIO pin services, using the new GPIO

descriptor API. Each GPIO pin is identified by a hardware dependent pair of chip (subsystem)

and line (pin) numbers. Use GPIO_line_open() to initialize and open a GPIO pin,

GPIO_line_read() to read from a GPIO pin, and GPIO_line_write() to write to a GPIO

pin.

Use GPIO_line_event() to wait for input edge events on a GPIO pin that has been

configured as an interrupt input.

libhidraw

http://git.munts.com/libsimpleio/doc/libhidraw.html

This library provides wrapper functions for the Linux raw HID device ioctl() services. The

Linux kernel raw HID subsystem creates a device node of the form /dev/hidrawN for each

raw HID device detected. Use HIDRAW_open() to open a raw HID device node by name.

Use HIDRAW_open_id() to open the first raw HID device to match the given vendor and

product identifiers. Use HIDRAW_send() to send a 64-byte message (aka HID report) to the

raw HID device. Use HIDRAW_receive() to obtain a 64-byte message (aka HID report) from

the raw HID device.

Note: The message size parameter passed to HIDRAW_send() and HIDRAW_receive()

will typically be 64 bytes, or 65 bytes if the raw HID device uses the first byte of the message

for the report number.

Note: HIDRAW_send() and HIDRAW_receive() are blocking functions. If you need to wait

for the raw HID device without blocking, you can register its file descriptor with

EVENT_register() and wait for something to happen with EVENT_wait().

libi2c

http://git.munts.com/libsimpleio/doc/libi2c.html

This library provides wrapper functions for the Linux I2C device ioctl() services. The Linux

kernel I2C subsystem creates a device node of the form /dev/i2c-N for each I2C bus

controller detected. Each I2C bus may have one or more slave devices attached to it. Use

I2C_open() to open an I2C bus controller device node by name. Use I2C_transaction()

to transmit a command and/or receive a response from a single I2C device.

A Simple I/O Library for Embedded Linux Systems – Revision 6, 4 February 2019 Page 10

liblinux

http://git.munts.com/libsimpleio/doc/liblinux.html

This library provides wrapper functions for certain Linux system calls. Use LINUX_detach()

to switch a running program from foreground to background execution. Use

LINUX_drop_privileges() change a running program's user (e.g. from root to nobody).

Use LINUX_openlog() to initialize a connection to the syslog facility. Use

LINUX_syslog() to post a message to the syslog facility. Use LINUX_strerror() to

retrieve the error message associated with an errno error number.

For the C or C++ programming languages, these wrapper functions offer no particular benefit

over the regular system call functions provided by glibc.

liblinx

http://git.munts.com/libsimpleio/doc/liblinx.html

https://www.labviewmakerhub.com/doku.php?id=learn:libraries:linx:spec:start

This library provides functions for sending and receiving messages between a client program

and a Labview LINX remote I/O device. To develop a LINX client program, use

LINX_transmit_command() and LINX_receive_response(). To develop a LINX

server program, use LINX_receive_command() and LINX_transmit_response(). All

four of these functions require an open byte stream file descriptor (e.g. from SERIAL_open()

or TCP4_connect()) as the first parameter.

Each of the receive functions returns after accepting one byte from the byte stream. A value of

zero in the error parameter indicates that the received byte has completed a frame and

EAGAIN indicates otherwise. Each of the receive functions must be called successively with

the same arguments until the frame has been completed.

Note: The receive functions block until a byte is available from the underlying byte stream. If

you need to wait without blocking, you can register the byte stream file descriptor with

EVENT_register() and wait for something to happen with EVENT_wait().

A Simple I/O Library for Embedded Linux Systems – Revision 6, 4 February 2019 Page 11

libpwm

http://git.munts.com/libsimpleio/doc/libpwm.html

This library provides functions for configuring and writing to PWM (Pulse Width Modulated)

output devices. The Linux kernel PWM subsystem populates sysfs entries for each PWM

output configured. PWM outputs are identified by chip and channel numbers. Use

PWM_configure() to configure a single PWM output. Use PWM_open() to open a single

PWM device node. Use PWM_write() to set the PWM output duty cycle.

Note: Many PWM controllers require the same PWM pulse frequency for all channels.

Therefore, configuring different pulse period values for different channels within the same

PWM controller may result in incorrect operation.

libserial

http://git.munts.com/libsimpleio/doc/libserial.html

This library provides wrapper functions for the Linux serial port termios services. The Linux

kernel serial port subsystem creates a device node of the form /dev/ttyXXXX for each serial

port device detected. Use SERIAL_open() to configure and open a serial port device by

name. Use SERIAL_send() to send data to a serial port device. Use SERIAL_receive()

to receive data from a serial port device.

Note: The file descriptor returned by SERIAL_open() may be passed to STREAM_send()

and STREAM_receive() as described below.

Note: SERIAL_send() and SERIAL_receive() are blocking functions. If you need to wait

for the serial port device without blocking, you can register its file descriptor with

EVENT_register() and wait for something to happen with EVENT_wait().

libspi

http://git.munts.com/libsimpleio/doc/libspi.html

This library provides wrapper functions for the Linux SPI device ioctl() services. The Linux

kernel SPI subsystem creates a device node of the form /dev/spidev-X.Y for each SPI

slave device detected. Use SPI_open() to open an SPI slave device node by name. Use

SPI_transaction() to transmit a command and/or receive a response from a single SPI

slave device.

Note: Some hardware platforms may not implement hardware controlled slave select output

signals. A GPIO pin file descriptor obtained with GPIO_open() may be passed to

SPI_transaction() to request software controlled slave select.

A Simple I/O Library for Embedded Linux Systems – Revision 6, 4 February 2019 Page 12

libstream

http://git.munts.com/libsimpleio/doc/libstream.html

http://git.munts.com/libsimpleio/doc/StreamFramingProtocol.pdf

This library provides functions for encoding and decoding byte stream data into frames as

specified in the Stream Framing Protocol. A common use case for this protocol is to

communicate with a microcontroller via a serial port. Use STREAM_encode_frame() to

encode a frame for transmission. Use STREAM_decode_frame() to decoded a received

frame. Use STREAM_send_frame() to transmit a frame via a byte stream indicated by a

Linux file descriptor. Use STREAM_receive_frame() to receive a frame via a byte stream

indicated by a Linux file descriptor.

STREAM_receive_frame() returns after accepting one byte from the byte stream. It will

return zero in the error parameter if that byte completes a frame and EAGAIN otherwise.

STREAM_receive_frame() must be called successively with the same arguments until the

frame has been completed.

Note: STREAM_receive_frame() blocks until a byte is available from the underlying byte

stream. If you need to wait without blocking, you can register the byte stream file descriptor

with EVENT_register() and wait for something to happen with EVENT_wait().

libipv4

http://git.munts.com/libsimpleio/doc/libipv4.html

This library provides wrapper functions for the Linux IPv4 socket services. Use

IPV4_resolve() to resolve a host name to a 32-bit integer IPv4 address. Use

IPV4_ntoa() to convert a 32-bit integer IPv4 address to a string, in dotted octet notation

(e.g. 1.2.3.4). Use TCP4_connect() to connect to a TCP server. Use TCP4_accept()

or TCP4_server() to implement a TCP server. Use TCP4_send() to send data and

TCP4_receive() to receive data.

Note: The file descriptor returned by TCP4_connect(), TCP4_accept(), or

TCP4_server() may be passed to STREAM_send() and STREAM_receive() as described

above.

Note: TCP4_send() and TCP4_receive() are blocking functions. If you need to wait

without blocking, you can register the file descriptor with EVENT_register() and wait for

something to happen with EVENT_wait().

A Simple I/O Library for Embedded Linux Systems – Revision 6, 4 February 2019 Page 13

libwatchdog

http://git.munts.com/libsimpleio/doc/libwatchdog.html

This library provides functions for configuring and resetting watch dog timer devices. The

Linux kernel watchdog timer subsystem creates a device node of the form /dev/watchdogN

for each watchdog timer. The default watchdog timer is /dev/watchdog. Use

WATCHDOG_open() to open a watchdog timer device node by name. Use

WATCHDOG_get_timeout() to query the current period in seconds, and

WATCHDOG_set_timeout() to change the period. Use WATCHDOG_kick() to reset the

watchdog timer.

A Simple I/O Library for Embedded Linux Systems – Revision 6, 4 February 2019 Page 14

Man Pages

A Simple I/O Library for Embedded Linux Systems – Revision 6, 4 February 2019 Page 15

libsimpleio(2) Linux Simple I/O Library libsimpleio(2)

NAME

libsimpleio −− Linux Simple I/O Library

DESCRIPTION

libsimpleio is an attempt to encapsulate (as much as possible) the ugliness of Linux I/O device access. It

provides services for reading and/or writing the following types of Linux I/O devices:

*Industrial I/O Subsystem A/D (Analog to Digital Converter) Devices

*Industrial I/O Subsystem D/A (Digital to Analog Converter) Devices

*GPIO (General Purpose Input/Output) Pins

*Raw HID (Human Interface Device) Devices

2C(Inter-Integrated Circuit) Bus Devices

*LabViewLINX Remote I/O Devices

*PWM (Pulse Width Modulated) Output Devices

*Serial Ports

*SPI (Serial Peripheral Interface) Bus Devices

*Stream Framing Protocol Devices

*TCP and UDP overIPv4 Network Devices

*Watchdog Timer Devices

Although libsimpleio wasoriginally intended for Linux microcomputers such as the Raspberry Pi, it can

also be useful on larger desktop Linux systems.

SEE ALSO

libadc(2), libdac(2), libevent(2), libgpio(2), libhidraw(2),

libi2c(2), libipv4(2), liblinux(2), liblinx(2), libpwm(2),

libserial(2), libspi(2), libstream(2), libwatchdog(2)

http://git.munts.com/libsimpleio/doc/UserManual.pdf

AUTHOR

Philip Munts, President, Munts AM Corp dba Munts Technologies

version 1 21 December 2018 16

libadc(2) Linux Simple I/O Library libadc(2)

NAME

libadc −− Linux Simple I/O Library: A/D Input Module

SYNOPSIS

#include <libsimpleio/libadc.h>

void ADC_get_name(int32_t chip,char *name,int32_t namesize,

int32_t *error);

void ADC_open(int32_t chip,int32_t channel,int32_t * fd,

int32_t *error);

void ADC_close(int32_t fd,int32_t *error);

void ADC_read(int32_t fd,int32_t *sample,int32_t *error);

Link with -lsimpleio.

DESCRIPTION

All functions return either 0(upon success) or an errno value (upon failure) in *error.

ADC_get_name() fetches an information string for an A/D device. The chip number must be passed in

chip.The destination buffer address must be passed in *name and the destination buffer size must be

passed in namesize.The minimum size for the destination buffer is 16 bytes.

ADC_open() opens an A/D input channel device. The A/D chip number must be passed in the chip

parameter and the A/D input channel number must be passed in the channel parameter.Upon success, a

ﬁle descriptor for the A/D input channel device is returned in *fd.

ADC_close() closes a previously opened A/D input channel device.

ADC_read() reads a sample from an A/D input channel device. The ﬁle descriptor for an open A/D input

channel device must be passed in the fd parameter.The analog sample data will be returned in the *sample

parameter.

SEE ALSO

libsimpleio(2), libdac(2), libevent(2), libgpio(2), libhidraw(2),

libi2c(2), libipv4(2), liblinux(2), liblinx(2), libpwm(2),

libserial(2), libspi(2), libstream(2), libwatchdog(2)

https://wiki.analog.com/software/linux/docs/iio/iio

AUTHOR

Philip Munts, President, Munts AM Corp dba Munts Technologies

version 1 21 December 2018 17

libdac(2) Linux Simple I/O Library libdac(2)

NAME

libdac −− Linux Simple I/O Library: D/A Input Module

SYNOPSIS

#include <libsimpleio/libdac.h>

void DAC_get_name(int32_t chip,char *name,int32_t namesize,

int32_t *error);

void DAC_open(int32_t chip,int32_t channel,int32_t * fd,

int32_t *error);

void DAC_close(int32_t fd,int32_t *error);

void DAC_write(int32_t fd,int32_t sample,int32_t *error);

Link with -lsimpleio.

DESCRIPTION

All functions return either 0(upon success) or an errno value (upon failure) in *error.

DAC_get_name() fetches an information string for a D/A device. The chip number must be passed in chip.

The destination buffer address must be passed in *name and the destination buffer size must be passed in

namesize.The minimum size for the destination buffer is 16 bytes.

DAC_open() opens a D/A output channel device. The D/A chip number must be passed in the chip

parameter and the D/A output channel number must be passed in the channel parameter.Upon success, a

ﬁle descriptor for the D/A output channel device is returned in *fd.

DAC_close() closes a previously opened D/A output channel device.

DAC_write() writes a sample to a D/A output channel device. The ﬁle descriptor for an open D/A output

channel device must be passed in the fd parameter.The analog sample data must be passed in the sample

parameter.

SEE ALSO

libsimpleio(2), libadc(2), libevent(2), libgpio(2), libhidraw(2),

libi2c(2), libipv4(2), liblinux(2), liblinx(2), libpwm(2),

libserial(2), libspi(2), libstream(2), libwatchdog(2)

https://wiki.analog.com/software/linux/docs/iio/iio

AUTHOR

Philip Munts, President, Munts AM Corp dba Munts Technologies

version 1 4February 2019 18

libevent(2) Linux Simple I/O Library libevent(2)

NAME

libevent −− Linux Simple I/O Library: Event Notiﬁcation Module

SYNOPSIS

#include <libsimpleio/libevent.h>

void EVENT_open(int32_t *epfd,int32_t *error);

void EVENT_close(int32_t epfd,int32_t *error);

void EVENT_register_fd(int32_t epfd,int32_t fd,int32_t events,

int32_t handle,int32_t *error);

void EVENT_modify_fd(int32_t epfd,int32_t fd,int32_t events,

int32_t handle,int32_t *error);

void EVENT_unregister_fd(int32_t epfd,int32_t fd,int32_t *error);

void EVENT_wait(int32_t epfd,int32_t * fd,int32_t *event,

int32_t *handle,int32_t timeoutms,int32_t *error);

Link with -lsimpleio.

DESCRIPTION

All functions return either 0(upon success) or an errno value (upon failure) in *error.

EVENT_open() must be called before anyofthe other functions, to open a connection to the epoll ev e nt

notiﬁcation subsystem.

EVENT_close() must be called to close the connection to the epoll subsystem.

EVENT_register_fd() registers the ﬁle descriptor fd for the event notiﬁcations selected by the events

parameter.Event notiﬁcation codes, such as EPOLLIN (input ready), are deﬁned in

/usr/include/sys/epoll.h,and may be OR’d together to register for more than one type of event notiﬁcation.

The handle parameter is passed in to the Linux kernel and will be passed back to EVENT_wait() when an

ev e nt notiﬁcation occurs.

EVENT_modify_fd() modiﬁes the event notiﬁcations enabled on a previously registered ﬁle descriptor.

The most common use case is to rearm a ﬁle descriptor registered with EPOLLONESHOT for further

ev e nt notiﬁcations. After such a ﬁle descriptor has delivered an event, it will be disabled from delivering

anyfurther event notiﬁcations until it is rearmed. The handle parameter is passed in to the Linux kernel

and will be passed back to EVENT_wait() when an event notiﬁcation occurs.

EVENT_unregister_fd() unregisters event notiﬁcations for the ﬁle descriptor fd.

EVENT_wait() waits until an event notiﬁcation occurs for anyofthe previously registered ﬁle descriptors.

The timeoutms parameter indicates the time in milliseconds to wait for an event notiﬁcation. Avalue of

zero indicates EVENT_wait() should return immediately whether or not an event notiﬁcation is available.

If an event notiﬁcation occurs before the timeout expires, *error will be set to 0,*fd and *event will be set

to the next available ﬁle descriptor and event notiﬁcation code, and *handle will be set to whatevervalue

wassupplied to EVENT_register_fd() or EVENT_modify_fd().Ifnoevent notiﬁcation occurs before the

timeout expires, *error will be set to EAGAIN and *fd,*event,and *handle will all be set to zero. If some

other error occurs, *error will be set to an errno value and *fd,*event,and *handle will all be set to zero.

SEE ALSO

libsimpleio(2), libadc(2), libdac(2), libgpio(2), libhidraw(2),

libi2c(2), libipv4(2), liblinux(2), liblinx(2), libpwm(2),

libserial(2), libspi(2), libstream(2), libwatchdog(2)

version 1 21 December 2018 19

libevent(2) Linux Simple I/O Library libevent(2)

AUTHOR

Philip Munts, President, Munts AM Corp dba Munts Technologies

version 1 21 December 2018 20

libgpio(2) Linux Simple I/O Library libgpio(2)

NAME

libgpio −− Linux Simple I/O Library: GPIO Module

SYNOPSIS

#include <libsimpleio/libgpio.h>

void GPIO_chip_info(int32_t chip,char *name,int32_t namesize,

char *label,int32_t labelsize,int32_t *lines,int32_t *error);

void GPIO_line_info(int32_t chip,int32_t line,int32_t * ﬂags,

char *name,int32_t namesize,char *label,int32_t labelsize,

int32_t error);

void GPIO_line_open(int32_t chip,int32_t line,int32_t ﬂags,

int32_t events,int32_t state,int32_t * fd,int32_t *error);

void GPIO_line_close(int32_t fd,int32_t *error);

void GPIO_line_read(int32_t fd,int32_t *state,int32_t *error);

void GPIO_line_write(int32_t fd,int32_t state,int32_t *error);

void GPIO_line_event(int32_t fd,int32_t *state,int32_t *error);

Deprecated sysfs API:

typedef enum

{

GPIO_DIRECTION_INPUT,

GPIO_DIRECTION_OUTPUT,

}GPIO_DIRECTION_t;

typedef enum

{

GPIO_EDGE_NONE,

GPIO_EDGE_RISING,

GPIO_EDGE_FALLING,

GPIO_EDGE_BOTH

}GPIO_EDGE_t;

typedef enum

{

GPIO_POLARITY_ACTIVELOW,

GPIO_POLARITY_ACTIVEHIGH,

}GPIO_POLARITY_t;

void GPIO_conﬁgure(int32_t pin,int32_t direction,int32_t state,

int32_t edge,int32_t polarity,int32_t *error);

void GPIO_open(int32_t pin,int32_t * fd,int32_t *error);

void GPIO_close(int32_t fd,int32_t *error);

void GPIO_read(int32_t fd,int32_t *state,int32_t *error);

version 1 21 December 2018 21

libgpio(2) Linux Simple I/O Library libgpio(2)

void GPIO_write(int32_t fd,int32_t state,int32_t *error);

Link with -lsimpleio.

DESCRIPTION

All functions return either 0(upon success) or an errno value (upon failure) in *error.

GPIO_chip_info() retrievesinformation about a particular GPIO chip (subsystem). The chip parameter

selects the particular GPIO chip. Information strings are returned in name and label (with maximum sizes

indicated by namesize and labelsize)and the number of GPIO lines (pins) available from this chip is

returned in lines.

GPIO_line_info() retrievesinformation about a particular GPIO pin. The chip and line parmeters select

the particular GPIO pin. Current conﬁguration ﬂags for the GPIO pin are returned in ﬂags.Information

strings are returned in name and label (with maximum sizes indicated by namesize and labelsize).

GPIO_line_open() conﬁgures and opens a single GPIO pin. The chip and line parmeters select the

particular GPIO pin. Requested conﬁguration ﬂags are passed in ﬂags,requested event (interrupt edge)

ﬂags are passed in events,and the initial state (0or 1)for output pins is passed in state.Upon success, a

ﬁle descriptor for the GPIO pin will be returned in *fd.

GPIO_line_close() closes a previously opened GPIO pin.

GPIO_line_read() gets the current state of a GPIO pin. The state (0or 1)ofthe GPIO pin will be returned

in *state.

GPIO_line_write() sets a GPIO pin output state. The newstate (0or 1)ispassed in the state parameter.

GPIO_line_event() waits (blocking the calling process) for an interrupt on an GPIO interrupt input pin

(conﬁgured with GPIOHANDLE_REQUEST_INPUT in the ﬂags parameter and

GPIOEVENT_REQUEST_RISING_EDGE,GPIOEVENT_REQUEST_FALLING_EDGE,or

GPIOEVENT_REQUEST_BOTH_EDGES in the events parameter to GPIO_line_open()). The state (0

or 1)ofthe GPIO pin after the interrupt will be returned in *state.

Deprecated sysfs API:

GPIO_conﬁgure() conﬁgures a single GPIO pin. The pin parameter selects the GPIO pin (as numbered

by the Linux kernel) to be conﬁgured. The direction parameter may be GPIO_DIRECTION_INPUT or

GPIO_DIRECTION_OUTPUT.For input pins, the state parameter must be 0.For output pins, the state

parameter may be 0or 1to set the initial state. Forinput pins, the edge parameter may be

GPIO_EDGE_NONE,GPIO_EDGE_RISING,GPIO_EDGE_FALLING,orGPIO_EDGE_BOTH.

Foroutput pins, the edge parameter must be GPIO_EDGE_NONE. The polarity parameter may be

GPIO_POLARITY_ACTIVELOW or GPIO_POLARITY_ACTIVEHIGH.

The udev rules included in the libsimpleio package will create a symbolic link from /dev/gpioxx to

/sys/class/gpio/gpioxx/value when a GPIO pin is conﬁgured.

GPIO_open() opens a GPIO pin device. The GPIO pin number is passed in the pin parameter.Upon

success, a ﬁle descriptor for the GPIO pin device is returned in *fd.

GPIO_close() closes a previously opened GPIO pin device.

GPIO_read() gets the current state of a GPIO pin. Upon success, the current state (0or 1)ofthe GPIO pin

will be returned in *state.

GPIO_write() sets a GPIO pin output state. The newstate (0or 1)ispassed in the state parameter.

SEE ALSO

libsimpleio(2), libadc(2), libdac(2), libevent(2), libhidraw(2),

libi2c(2), libipv4(2), liblinux(2), liblinx(2), libpwm(2),

libserial(2), libspi(2), libstream(2), libwatchdog(2)

version 1 21 December 2018 22

libgpio(2) Linux Simple I/O Library libgpio(2)

AUTHOR

Philip Munts, President, Munts AM Corp dba Munts Technologies

version 1 21 December 2018 23

libhidraw(2) Linux Simple I/O Library libhidraw(2)

NAME

libhidraw −− Linux Simple I/O Library: RawHID Module

SYNOPSIS

#include <libsimpleio/libhidraw.h>

void HIDRAW_open(const char *name,int32_t * fd,int32_t *error);

void HIDRAW_open_id(int32_t VID,int32_t PID,int32_t * fd,

int32_t *error);

void HIDRAW_close(int32_t fd,int32_t *error);

void HIDRAW_get_name(int32_t fd,char *name,int32_t namesize,

int32_t *error);

void HIDRAW_get_info(int32_t fd,int32_t *bustype,int32_t *vendor,

int32_t * product,int32_t *error);

void HIDRAW_send(int32_t fd,void *buf,int32_t bufsize,

int32_t *count,int32_t *error);

void HIDRAW_receive(int32_t fd,void *buf,int32_t bufsize,

int32_t *count,int32_t *error);

Link with -lsimpleio.

DESCRIPTION

All functions return either 0(upon success) or an errno value (upon failure) in *error.

HIDRAW_open() opens a rawHID device by name. The device node name (/dev/hidrawN)must be

passed in name.Upon success, a ﬁle descriptor for the rawHID device is returned in *fd.

HIDRAW_open_id() opens the ﬁrst rawHID device that matches the speciﬁed vendor and product ID

numbers passed in VID and PID.Upon success, a ﬁle descriptor for the rawhid device is returned in *fd.

HIDRAW_close() closes a previously opened rawHID device. The HID device ﬁle descriptor must be

passed in fd.

HIDRAW_get_name() fetches an information string from the rawHID device. The HID device ﬁle

descriptor must be passed in fd.The destination buffer address must be passed in *name and the

destination buffer size must be passed in namesize.The minimum size for the destination buffer is 16

bytes.

HIDRAW_get_info() fetches the bus type, vendor ID and product ID from the rawHID device. The HID

device ﬁle descriptor must be passed in fd.The bus type is returned in *bustype,and may be BUS_USB,

BUS_HIL,BUS_BLUETOOTH or BUS_VIRTUAL.These values are deﬁned in

/usr/include/linux/input.h.The vendor and product ID’sare returned in *vendor and *product

respectively.

HIDRAW_send() sends a message (also known as a HID report) to the rawHID device. The HID device

ﬁle descriptor must be passed in fd.The address of the message buffer must be passed in bufand the size

of the message buffer must be passed in bufsize.The message size will typically be either 64 or 65 bytes,

depending on whether the particular rawHID device uses the ﬁrst byte for the report number.Upon

success, the number of bytes actually sent will be returned in *count.

HIDRAW_receive() receivesamessage (i.e. a HID report) from the rawHID device. The HID device ﬁle

descriptor must be passed in fd.The address of the message buffer must be passed in bufand the size of the

message buffer must be passed in bufsize.The message size will typically be either 64 or 65 bytes,

depending on whether the particular rawHID device uses the ﬁrst byte for the report number.Upon

version 1 21 December 2018 24

libhidraw(2) Linux Simple I/O Library libhidraw(2)

success, the number of bytes actually receivedwill be returned in *count.

SEE ALSO

libsimpleio(2), libadc(2), libdac(2), libevent(2), libgpio(2),

libi2c(2), libipv4(2), liblinux(2), liblinx(2), libpwm(2),

libserial(2), libspi(2), libstream(2), libwatchdog(2)

AUTHOR

Philip Munts, President, Munts AM Corp dba Munts Technologies

version 1 21 December 2018 25

libi2c(2) Linux Simple I/O Library libi2c(2)

NAME

libi2c −− Linux Simple I/O Library: I2CModule

SYNOPSIS

#include <libsimpleio/libi2c.h>

void I2C_open(const char *name,int32_t * fd,int32_t * error);

void I2C_close(int32_t fd,int32_t *error);

void I2C_transaction(int32_t fd,int32_t slaveaddr,void *cmd,int32_t cmdlen,

void *resp,int32_t resplen,int32_t *error);

Link with -lsimpleio.

DESCRIPTION

All functions return either 0(upon success) or an errno value (upon failure) in *error.

I2C_open() opens an I2Cbus controller device. The device name, /dev/i2c-x,must be passed in the name

parameter.Upon success, a ﬁle descriptor for the I2Cbus controller device is returned in *fd.

I2C_close() closes a previously opened I2Cbus controller device.

I2C_transaction() performs a single I2Cbus transaction, with optional transmit and receive phases. The

I2Cslave device address must be passed in the slaveaddr parameter.Either the address of a command

message and its length must be passed in the cmd and cmdlen parameters, or NULL and 0for a receive

only transaction. Either the address of a receive buffer and its size must be passed in the resp and resplen

parameters, or NULL and 0for a transmit only transaction.

SEE ALSO

libsimpleio(2), libadc(2), libdac(2), libevent(2), libgpio(2),

libhidraw(2), libipv4(2), liblinux(2), liblinx(2), libpwm(2),

libserial(2), libspi(2), libstream(2), libwatchdog(2)

AUTHOR

Philip Munts, President, Munts AM Corp dba Munts Technologies

version 1 21 December 2018 26

libipv4(2) Linux Simple I/O Library libipv4(2)

NAME

libipv4 −− Linux Simple I/O Library: IPv4 TCP Module

SYNOPSIS

#include <libsimpleio/libipv4.h>

void IPV4_resolve(char *name,int32_t *addr,int32_t *error);

void IPV4_ntoa(int32_t addr,char *dst,int32_t dstsize,int32_t *error);

void TCP4_connect(int32_t addr,int32_t port,int32_t * fd,int32_t *error);

void TCP4_accept(int32_t addr,int32_t port,int32_t * fd,int32_t *error);

void TCP4_server(int32_t addr,int32_t port,int32_t * fd,int32_t *error);

void TCP4_close(int32_t fd,int32_t *error);

void TCP4_send(int32_t fd,void *buf,int32_t bufsize,int32_t *count,

int32_t *error);

void TCP4_receive(int32_t fd,void *buf,int32_t bufsize,int32_t *count,

int32_t *error);

void UDP4_open(int32_t addr,int32_t port,int32_t * fd,int32_t *error);

void UDP4_close(int32_t fd,int32_t *error);

void UDP4_send(int32_t fd,int32_t addr,int32_t port,void *buf,

int32_t bufsize,int32_t ﬂags,int32_t *count,int32_t *error);

void UDP4_receive(int32_t fd,int32_t *addr,int32_t * port,void *buf,

int32_t bufsize,int32_t ﬂags,int32_t *count,int32_t *error);

Link with -lsimpleio.

DESCRIPTION

All functions return either 0(upon success) or an errno value (upon failure) in *error.

IPV4_resolve() attempts to resolveanIPv4 address string passed in *name (containing a domain name, a

local host name like localhost or a dotted decimal address like 1.2.3.4). Upon success, the 32-bit IPv4

address will be returned in *addr.

IPV4_ntoa() converts an IPv4 address to a dotted decimal address string. The address of the destination

buffer is passed in *dst and its size, which must be at least 16 bytes, is passed in dstsize.Upon success, the

dotted decimal address string will be returned in *dst.

TCP4_connect() attempts to connect to a IPv4 TCP server.The 32-bit IPv4 address is passed in addr and

the 16-bit TCP port number is passed in port.Upon successful connection, a stream ﬁle descriptor will be

returned in *fd.

TCP4_accept() waits for an incoming connection request from a IPv4 TCP client. Either INADDR_ANY

may be passed in addr to bind to (i.e. listen on) all network interfaces, or the 32-bit IPV4 address of a

particular network interface may be passed to bind to only that interface. The 16-bit TCP port number is

passed in port.Upon successful connection, a stream ﬁle descriptor will be returned in *fd.

TCP4_server() operates like TCP4_accept() except that upon successful connection, the original server

process forks to create a newand separate connection handler process. The server process continues to

listen for more connection requests, without returning from TCP4_server(), while in the newconnection

handler process, TCP4_server() does return, with a stream ﬁle descriptor for the newconnection returned

version 1 21 December 2018 27

libipv4(2) Linux Simple I/O Library libipv4(2)

in *fd.

TCP4_close() closes a previously opened IPv4 TCP stream. The stream ﬁle descriptor is passed in fd.

TCP4_send() sends data to a IPv4 TCP stream. The stream ﬁle descriptor is passed in fd.The transmit

buffer address is passed in bufand its size is passed in bufsize.Upon success, the number of bytes actually

sent will be returned in *count.

TCP4_receive() receivesdata from a IPv4 TCP stream. The stream ﬁle descriptor is passed in fd.The

receive buffer address is passed in bufand its size is passed in bufsize.Upon success, the number of bytes

actually receivedwill be returned in *count.

UDP4_open() opens a UDP datagram socket. The IP address of the network interface to bind the socket to

is passed in the addr parameter.Avalue of zero or INADDR_ANY indicates the socket should bind to all

network interfaces. The UDP port number is passed in the port parameter.Avalue of zero indicates the

kernel should automatically select a port number.Upon successful completion, a UDP socket ﬁle

descriptor will be returned in *fd.

UDP4_close() closes a previously opened UDP socket. The UDP socket ﬁle descriptor is passed in fd.

UDP4_send() sends a UDP datagram. The UDP socket ﬁle descriptor is passed in fd.The IPv4 address of

the destination network node is passed in addr.The UDP port number of the destination network node is

passed in port.The UDP datagram is passed in *buf and its size in bytes is passed in bufsize.Flags for the

sendto() Linux system call are passed in ﬂags.The number of bytes sent will be returned in *count.

UDP4_receive() receivesaUDP datagram. The UDP socket ﬁle descriptor is passed in fd.The IPv4

address of the source network node will be returned in *addr.The UDP port number of the source network

node will be returned in *port.The UDP datagram will be returned in *buf .The size of the datagram

buffer will be passed in bufsize.Flags for the recvfrom() Linux system call are passed in ﬂags.The

number of bytes receivedwill be returned in *count.

SEE ALSO

libsimpleio(2), libadc(2), libdac(2), libevent(2), libgpio(2),

libhidraw(2), libi2c(2), liblinux(2), liblinx(2), libpwm(2),

libserial(2), libspi(2), libstream(2), libwatchdog(2)

AUTHOR

Philip Munts, President, Munts AM Corp dba Munts Technologies

version 1 21 December 2018 28

liblinux(2) Linux Simple I/O Library liblinux(2)

NAME

liblinux −− Linux Simple I/O Library: Linux System Call Wrapper Module

SYNOPSIS

#include <libsimpleio/liblinux.h>

void LINUX_detach(int32_t *error);

void LINUX_drop_privileges(const char *username,int32_t *error);

void LINUX_openlog(const char *id,int32_t options,int32_t facility,

int32_t *error);

void LINUX_syslog(int32_t priority,const char *msg,int32_t *error);

void LINUX_strerror(int32_t error,char *buf,int32_t bufsize);

void LINUX_poll(int32_t numﬁles,int32_t * ﬁles,int32_t *events,

int32_t *results,int32_t timeout,int32_t *error);

void LINUX_usleep(int32_t microseconds,int32_t *error);

void LINUX_command(const char *cmd,int32_t *status,int32_t *error);

Link with -lsimpleio.

DESCRIPTION

These functions wrap certain useful Linux system calls for use by other programming languages such as

Ada, C#, Java,and Pascal. Theyare provided for the convenience of devlopers using libsimpleio with

those langauges. For the C programming language, theyoffer no particular beneﬁt overthe regular system

call wrappers.

All functions return either 0(upon success) or an errno value (upon failure) in *error.

LINUX_detach() detaches the calling process from its controlling terminal and continues execution in the

background.

LINUX_drop_privileges() allows a process started by the superuser to drop its privileges to those of the

user speciﬁed by the username parameter.

LINUX_openlog() opens a connection to the syslog message logger.The options and facility parameters

accept the same values as the openlog() system library function.

LINUX_syslog() transmits a text message supplied in the msg parameter to the syslog message logger.The

priority parameter accepts the same values as the syslog() system library function.

LINUX_strerror() retrievesthe error message for the errno value passed in the error parameter.A

destination buffer address and size must be passed in the bufand bufsize parameters.

LINUX_poll() waits for events on an set of ﬁle descriptors. The number of ﬁle descriptors is passed in the

numﬁles parameter.Anarray of ﬁle descriptors is passed in the ﬁles parameter.Anarray of requested

ev e nts, using the same values as the poll() system library function, is passed in the events parameter.The

results for each ﬁle descriptor,also using the same values as the poll() system library function, will be

returned in the results parameter.Atimeout in milliseconds may be passed in the timeout parameter.A

timeout of zero indicates an immediate return without waiting at all. Atimeout of -1 indicates waiting

forever. Ifthe timeout expires without anyevent on anyﬁle descriptor occurring, then error will be set to

EAGAIN.

LINUX_usleep() causes the calling program to sleep for the period indicated by microseconds,bycalling

the usleep() system library function.

version 1 21 December 2018 29

liblinux(2) Linux Simple I/O Library liblinux(2)

LINUX_command() passes the shell command string speciﬁed by the cmd parameter to the system()

system library function for execution. The return value from the shell command will be returned in status.

SEE ALSO

libsimpleio(2), libadc(2), libdac(2), libevent(2), libgpio(2),

libhidraw(2), libi2c(2), libipv4(2), liblinx(2), libpwm(2),

libserial(2), libspi(2), libstream(2), libwatchdog(2)

AUTHOR

Philip Munts, President, Munts AM Corp dba Munts Technologies

version 1 21 December 2018 30

liblinx(2) Linux Simple I/O Library liblinx(2)

NAME

liblinx −− Linux Simple I/O Library: LabViewLINX Remote I/O Module

SYNOPSIS

#include <libsimpleio/liblinx.h>

Structures:

typedef struct

{

uint8_t SoF;

uint8_t Pack etSize;

uint16_t Pack etNum;

uint16_t Command;

uint8_t Args[54];

}LINX_command_t;

typedef struct

{

uint8_t SoF;

uint8_t Pack etSize;

uint16_t Pack etNum;

uint8_t Status;

uint8_t Data[55];

}LINX_response_t;

Server Routines:

void LINX_receive_command(int32_t fd,LINX_command_t *cmd,int32_t *count,int32_t *error);

void LINX_transmit_response(int32_t fd,LINX_response_t *resp,int32_t *error);

Client Routines:

void LINX_transmit_command(int32_t fd,LINX_command_t *cmd,int32_t *error);

void LINX_receive_response(int32_t fd,LINX_response_t *resp,int32_t *count,int32_t *error);

Byte Packing Routines:

uint16_t LINX_makeu16(uint8_t b0,uint8_t b1);

uint32_t LINX_makeu32(uint8_t b0,uint8_t b1, uint8_t b2,uint8_t b3);

Byte Unpacking Routines:

uint8_t LINX_splitu16(uint16_t u16,int32_t bn);

uint8_t LINX_splitu32(uint32_t u32,int32_t bn);

Link with -lsimpleio.

DESCRIPTION

These routines perform framing and encoding or decoding of LabViewLINX remote I/O commands (from

client to server) and responses (from server to client) to and from a bidirectional byte stream, which will

typically be either a serial port or a network socket.

version 1 21 December 2018 31

liblinx(2) Linux Simple I/O Library liblinx(2)

The transmit routines encode a frame from a command or response structure and write it to the stream

indicated by the stream ﬁle descriptor fd.Ifthe frame was written to the stream successfully, *error will be

set to zero, otherwise it will be set to an errno value.

The receive routines read exactly one byte from the stream indicated by the stream ﬁle descriptor fd.Ifthe

byte was read successfully and completes a frame, *error will be set to zero. If a byte was read

successfully,but did not complete a frame, *error will be set to EAGAIN. If the read failed, *error will be

set to an errno value and the previous data discarded. Successive calls to each receive routine must pass

the same command or response structure. The *count parameter preserves a byte counter between

successive function calls.

ALINX server running on some hardware device will typically have a message loop that calls

LINX_receive_command() to get each command from the LINX client, do some work, and then call

LINX_transmit_response() to return results to the client.

ALINX client will typically call LINX_transmit_command() to send each command to the server and

immediately thereafter call LINX_receive_response() to receive the results from the server.

The byte packing routines LINX_makeu16() and LINX_makeu32() pack twoorfour unsigned bytes into

a16-bit or 32-bit unsigned integer. b0 is the most signiﬁcant byte and b1 or b3 is the least signiﬁcant byte.

The byte unpacking routines LINX_splitu16() and LINX_splitu32() return a signle unsigned byte of a

16-bit or 32-bit unsigned integer,selected by the bn byte indexparameter.Abyte indexof0selects the

most signiﬁcant byte and a byte indexof1or 3selects the least signiﬁcant byte.

SEE ALSO

libsimpleio(2), libadc(2), libdac(2), libevent(2), libgpio(2),

libhidraw(2), libi2c(2), libipv4(2), liblinux(2), libpwm(2),

libserial(2), libspi(2), libstream(2), libwatchdog(2)

https://www.labviewmakerhub.com/doku.php?id=learn:libraries:linx:spec:start

AUTHOR

Philip Munts, President, Munts AM Corp dba Munts Technologies

version 1 21 December 2018 32

libpwm(2) Linux Simple I/O Library libpwm(2)

NAME

libpwm −− Linux Simple I/O Library: PWM Output Module

SYNOPSIS

#include <libsimpleio/libpwm.h>

typedef enum

{

PWM_POLARITY_ACTIVELOW,

PWM_POLARITY_ACTIVEHIGH,

}PWM_POLARITY_t;

void PWM_conﬁgure(int32_t chip,int32_t channel,int32_t period,

int32_t ontime,int32_t polarity,int32_t *error);

void PWM_open(int32_t chip,int32_t channel,int32_t * fd,

int32_t *error);

void PWM_close(int32_t fd,int32_t *error);

void PWM_write(int32_t fd,int32_t ontime,int32_t *error);

Link with -lsimpleio.

DESCRIPTION

All functions return either 0(upon success) or an errno value (upon failure) in *error.

PWM_conﬁgure() conﬁgures a single PWM output. The chip parameter selects the PWM controller chip

(as numbered by the Linux kernel) and the channel parameter selects the PWM output (also as numbered

by the Linux kernel) to be conﬁgured. The period parameter sets the PWM output pulse period in

nanoseconds. Note that manyPWM controllers require the same PWM pulse frequencyfor all channels.

Therefore, conﬁguring different pulse period values for different channels within the same PWM controller

may result in incorrect operation. The ontime parameter sets the initial PWM output pulse width in

nanoseconds. The polarity parameter sets the PWM output polarity and may be

PWM_POLARITY_ACTIVELOW or PWM_POLARITY_ACTIVEHIGH.Note that some PWM

controllers will not allowthe PWM_POLARITY_ACTIVELOW setting.

PWM_open() opens a (previously) conﬁgured PWM output device. The PWM controller chip number

must be passed in the chip parameter and the PWM output number must be passed in the channel

parameter.Upon success, a ﬁle descriptor for the PWM output device is returned in *fd.

PWM_close() closes a previously opened PWM output device.

PWM_write() changes the PWM output pulse width. The ﬁle descriptor for an open PWM output device

must be passed in the fd parameter.The newPWM output pulse width in nanoseconds must be passed in

the ontime parameter.

SEE ALSO

libsimpleio(2), libadc(2), libdac(2), libevent(2), libgpio(2),

libhidraw(2), libi2c(2), libipv4(2), liblinux(2), liblinx(2),

libserial(2), libspi(2), libstream(2), libwatchdog(2)

AUTHOR

Philip Munts, President, Munts AM Corp dba Munts Technologies

version 1 21 December 2018 33

libserial(2) Linux Simple I/O Library libserial(2)

NAME

libserial −− Linux Simple I/O Library: Asynchronous Serial Port Module

SYNOPSIS

#include <libsimpleio/libserial.h>

typedef enum

{

SERIAL_PARITY_NONE,

SERIAL_PARITY_EVEN,

SERIAL_PARITY_ODD,

}SERIAL_PARITY_t;

void SERIAL_open(const char *name,int32_t baudrate,int32_t parity,

int32_t databits,int32_t stopbits,int32_t * fd,int32_t *error);

void SERIAL_close(int32_t fd,int32_t *error);

void SERIAL_send(int32_t fd,void *buf,int32_t bufsize,

int32_t *count,int32_t *error);

void SERIAL_receive(int32_t fd,void *buf,int32_t bufsize,

int32_t *count,int32_t *error);

Link with -lsimpleio.

DESCRIPTION

All functions return either 0(upon success) or an errno value (upon failure) in *error.

SERIAL_open() opens and conﬁgures a serial port device. The device name must be passed in the name

parameter.The baudrate parameter sets the serial port bit rate. Allowed values are 50,75,110,134,150,

200,300,600,1200,1800,2400,4800,9600,19200,38400,57600,115200,and 230400.The parity

parameter sets the parity mode. Allowed values are SERIAL_PARITY_NONE,

SERIAL_PARITY_EVEN,and SERIAL_PARITY_ODD.The databits parameter sets the number of

bits per character,and may be from 5to 8.The stopbits parameter sets the number of stop bits per

character,and may be 1or 2.Upon success, a ﬁle descriptor for the serial port device is returned in *fd.

SERIAL_close() closes a previously opened serial port device. The serial port device ﬁle descriptor is

passed in fd.

SERIAL_send() sends data to the serial port device. The serial port device ﬁle descriptor is passed in fd.

The transmit buffer address is passed in bufand its size is passed in bufsize.Upon success, the number of

bytes actually sent will be returned in *count.

SERIAL_receive() receivesdata from the serial port device. The serial port device ﬁle descriptor is passed

in fd.The receive buffer address is passed in bufand its size is passed in bufsize.Upon success, the

number of bytes actually receivedwill be returned in *count.

SEE ALSO

libsimpleio(2), libadc(2), libdac(2), libevent(2), libgpio(2),

libhidraw(2), libi2c(2), libipv4(2), liblinux(2), liblinx(2),

libpwm(2), libspi(2), libstream(2), libwatchdog(2)

AUTHOR

Philip Munts, President, Munts AM Corp dba Munts Technologies

version 1 21 December 2018 34

libspi(2) Linux Simple I/O Library libspi(2)

NAME

libspi −− Linux Simple I/O Library: SPI Module

SYNOPSIS

#include <libsimpleio/libspi.h>

void SPI_open(const char *name,int32_t mode,int32_t wordsize,

int32_t speed,int32_t * fd,int32_t * error);

void SPI_close(int32_t fd,int32_t *error);

void SPI_transaction(int32_t spifd,int32_t csfd,void *cmd,

int32_t cmdlen,int32_t delayus,void *resp,int32_t resplen,

int32_t *error);

Link with -lsimpleio.

DESCRIPTION

All functions return either 0(upon success) or an errno value (upon failure) in *error.

SPI_open() opens an SPI slave device. The device name, /dev/spidevx.x,must be passed in the name

parameter.The mode parameter speciﬁes the SPI bus transfer mode, 0to 3.The wordsize parameter

speciﬁes the SPI bus transfer unit size, usually 8,16,or32 bits. Some SPI controllers only allow8-bit

transfers. The speed parameter speciﬁes the SPI bus transfer speed in bits per second. Upon success, a ﬁle

descriptor for the SPI slave device is returned in *fd.

SPI_close() closes a previously opened SPI slave device.

SPI_transaction() performs a single SPI bus transaction, with optional transmit and receive phases. Either

the address of a command message and its length must be passed in the cmd and cmdlen parameters, or

NULL and 0for a receive only transaction. The delayus parameter indicates the time in microseconds

between the transmit and receive phases. It should be set long enough for the SPI slave device to execute

the command and generate its response. Either the address of a receive buffer and its size must be passed in

the resp and resplen parameters, or NULL and 0for a transmit only transaction. The csfd parameter should

be set to SPI_CS_AUTO to use the hardware controlled slave chip select signal or set to the open ﬁle

descriptor for a GPIO pin to use for the software controlled slave chip select signal.

SEE ALSO

libsimpleio(2), libadc(2), libdac(2), libevent(2), libgpio(2),

libhidraw(2), libi2c(2), libipv4(2), liblinux(2), liblinx(2),

libpwm(2), libserial(2), libstream(2), libwatchdog(2)

AUTHOR

Philip Munts, President, Munts AM Corp dba Munts Technologies

version 1 21 December 2018 35

libstream(2) Linux Simple I/O Library libstream(2)

NAME

libstream −− Linux Simple I/O Library: Stream Framing Protocol Module

SYNOPSIS

#include <libsimpleio/libstream.h>

typedef ssize_t (*STREAM_readfn_t)(int fd,void *buf,size_t count);

typedef ssize_t (*STREAM_writefn_t)(int fd,const void *buf,

size_t count);

void STREAM_change_readfn(STREAM_readfn_t newread,int32_t *error);

void STREAM_change_writefn(STREAM_writefn_t newwrite,int32_t *error);

void STREAM_encode_frame(void *src,int32_t srclen,void *dst,

int32_t dstsize,int32_t *dstlen,int32_t *error);

void STREAM_decode_frame(void *src,int32_t srclen,void *dst,

int32_t dstsize,int32_t *dstlen,int32_t *error);

void STREAM_send_frame(int32_t fd,void *buf,int32_t bufsize,

int32_t *count,int32_t *error);

void STREAM_receive_frame(int32_t fd,void *buf,int32_t bufsize,

int32_t * framesize,int32_t *error);

Link with -lsimpleio.

DESCRIPTION

These functions encode, decode, send, and receive frames to and from a bidirectional byte stream, which

will typically be either a serial port or a network socket. The frames are encoded according the the Stream

Framing Procotol. See belowfor a link to the protocol speciﬁcation.

All functions return either 0(upon success) or an errno value (upon failure) in *error.

STREAM_change_readfn() changes the function used to read from the underlying stream from the

default read() to some other compatible function.

STREAM_change_writefn() changes the function used to write to the underlying stream from the default

write() to some other compatible function.

STREAM_encode_frame() encodes the message passed in *src,with its length passed in srclen.Empty

messages (srclen==0) are allowed. The encoded frame will be returned in *dst,whose maximum size must

be passed in dstsize.The size of the destination buffer must be at least 2 * srclen +8bytes. The actual size

of the encoded frame will be returned in *dstlen.

STREAM_decode_frame() decodes the frame passed in *src,with its length passed in srclen.The

decoded message will be returned in *dst,whose maximum size must be passed in dstsize.The actual size

of the decoded message will be returned in *dstlen.

STREAM_send_frame() writes an encoded frame to the bidirectional byte stream indicated by the ﬁle

descriptor fd.The encoded frame is passed in bufand its size is passed in bufsize.Upon success, the

number of bytes actually sent will be returned in *count.

STREAM_receive_frame() reads one byte from the bidirectional byte stream indicated by the ﬁle

descriptor fd and attempts to assemble a frame. It should be called repeatedly with the same *buf ,bufsize,

and *framesize parameters. The *framesize parameter is incremented for each byte received, and zeroed if

an error occurs. The *error parameter will be set to EAGAIN while a frame is being assembled. Upon

successful assembly of a complete frame, its size will be returned in *framesize and zero returned in *error.

version 1 21 December 2018 36

libstream(2) Linux Simple I/O Library libstream(2)

SEE ALSO

libsimpleio(2), libadc(2), libdac(2), libevent(2), libgpio(2),

libhidraw(2), libi2c(2), libipv4(2), liblinux(2), liblinx(2),

libpwm(2), libserial(2), libspi(2), libwatchdog(2)

http://git.munts.com/libsimpleio/doc/StreamFramingProtocol.pdf

AUTHOR

Philip Munts, President, Munts AM Corp dba Munts Technologies

version 1 21 December 2018 37

libwatchdog(2) Linux Simple I/O Library libwatchdog(2)

NAME

libwatchdog −− Linux Simple I/O Library: Watchdog Timer Module

SYNOPSIS

#include <libsimpleio/libwatchdog.h>

void WATCHDOG_open(const char *name,int32_t * fd,int32_t * error);

void WATCHDOG_close(int32_t fd,int32_t *error);

void WATCHDOG_get_timeout(int32_t fd,int32_t *timeout,int32_t *error);

void WATCHDOG_set_timeout(int32_t fd,int32_t newtimeout,

int32_t *timeout,int32_t *error);

void WATCHDOG_kick(int32_t fd,int32_t *error);

Link with -lsimpleio.

DESCRIPTION

All functions return either 0(upon success) or an errno value (upon failure) in *error.

WA T CHDOG_open() opens a watchdog timer device. The device node name, usually /dev/watchdog,

must be passed in the name parameter.Upon success, a ﬁle descriptor for the watchdog timer device is

returned in *fd.

WA T CHDOG_close() closes a previously opened watchdog timer device. Note that this may result in

watchdog timer expiration and subsequent system reset.

WA T CHDOG_get_timeout() may be used to discoverthe current watchdog timeout period. Upon

success, the watchdog period in seconds will be returned in *timeout.

WA T CHDOG_set_timeout() may be used to change the watchdog timeout period. The requested new

timeout period in seconds must be passed in newtimeout.Upon success, the actual newwatchdog period in

seconds will be returned in *timeout.Note that the newwatchdog period may be different from that

requested. For example, if the watchdog timer device has a granularity of one minute, requesting a timeout

of 45 seconds will result in an actual timeout of 60 seconds. Also note that the particular watchdog timer

device may not allowincreasing the timeout or may not allowchanging it at all.

WA T CHDOG_kick() may be used to reset the watchdog timer.

SEE ALSO

libsimpleio(2), libadc(2), libdac(2), libevent(2), libgpio(2),

libhidraw(2), libi2c(2), libipv4(2), liblinux(2), liblinx(2),

libpwm(2), libserial(2), libspi(2), libstream(2)

AUTHOR

Philip Munts, President, Munts AM Corp dba Munts Technologies

version 1 21 December 2018 38

User Manual

Navigation menu

Versions of this User Manual:

Views

Navigation