path: root/doc/instrument-control.texi

\input texinfo @c -*-texinfo-*-
@c Copyright (c) 2019-2024, John Donoghue <john.donoghue@ieee.org>
@c Octave Instrument Control Toolkit - Low level I/O functions for serial, i2c, parallel, tcp, gpib, vxi11, udp and usbtmc interfaces.

@c %*** Start of HEADER
@setfilename instrument-control.info
@settitle Octave Instrument Control Toolkit
@afourpaper
@paragraphindent 0
@finalout
@set COPYRIGHT_DATE 2019-2024
@c @afourwide
@c %*** End of the HEADER

@include version.texi
@include macros.texi

@macro boxnote {args}
@cartouche
@strong{NOTE}: \args\
@end cartouche
@end macro


@c %*** Start of TITLEPAGE
@titlepage
@title Octave Instrument Control Toolkit @value{VERSION}
@subtitle Low level instrumentation functions for @acronym{GNU} Octave.
@author John Donoghue
@page
@vskip 0pt plus 1filll
Copyright @copyright{} @value{COPYRIGHT_DATE} John Donoghue

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the same conditions as for modified versions.

@page
@heading Distribution
The @acronym{GNU} Octave Instrument Control Toolkit is @dfn{free} software.
Free software is a matter of the users' freedom to run, copy, distribute,
study, change and improve the software.
This means that everyone is free to use it and free to redistribute it
on certain conditions.  The @acronym{GNU} Octave Instrument Control toolkit
is not, however, in the public domain.  It is copyrighted and there are
restrictions on its distribution, but the restrictions are designed to
ensure that others will have the same freedom to use and redistribute
Octave that you have.  The precise conditions can be found in the
@acronym{GNU} General Public License that comes with the @acronym{GNU}
Octave Instrument Control toolkit and that also appears in @ref{Copying}.

To download a copy of the @acronym{GNU} Octave Instrument Control Toolkit, please visit
@url{http://octave.sourceforge.net/instrument-control/}.

@end titlepage
@c %*** End of TITLEPAGE

@c %*** Start of BODY
@contents
@ifnottex
@node Top
@top Introduction
The Instrument Control toolkit is a set of low level I/O functions for serial, i2c, spi, modbus, parallel, tcp, gpib, vxi11, udp and usbtmc interfaces
@end ifnottex

@menu
* Installing and loading::    Installing and loading the toolkit
* Basic Usage Overview::      Basic Usage Overview
* Function Reference::        Instrument Control functions
* Copying::                   Copying
* Index::                     Index
@end menu

@c -------------------------------------------------------------------------
@node Installing and loading
@chapter Installing and loading
@cindex Installing and loading

The Instrument Control toolkit must be installed and then loaded to be used.

It can be installed in @acronym{GNU} Octave directly from octave-forge,
or can be installed in an off-line mode via a downloaded tarball.

The toolkit must be then be loaded once per each @acronym{GNU} Octave session in order to use its functionality.

@section Requirements
@cindex Requirements
For GPIB support (Linux only), linux-gpib must be installed before installing instrument-control. 
GPIB support is also available for windows by following the information from the wiki:
https://wiki.octave.org/Instrument_control_package#Requirements

For VXI11 support, rpcgen, and libtirpc-devel must be installed before installing instrument-control. 

For MODBUS support, the libmodbus-devel must be installed before installing instrument-control.

@section Windows install
@cindex Windows install

If using the @acronym{GNU} Octave installer in Windows, the toolkit will have already been installed, and does not need to be re-installed
unless a newer version is available.

Run the following command to verify if the toolkit is available:

@example
pkg list instrument-control
@end example

@section Online Direct install
@cindex Online install
With an internet connection available, toolkit can be installed from
octave-forge using the following command within @acronym{GNU} Octave:

@example
pkg install -forge instrument-control
@end example

The latest released version of the toolkit will be downloaded, compiled and installed.

@section Off-line install
@cindex Off-line install
With the toolkit package already downloaded, and in the current directory when running
@acronym{GNU} Octave, the package can be installed using the following command within @acronym{GNU} Octave:

@example
pkg install instrument-control-@value{VERSION}.tar.gz
@end example

@section Loading
@cindex Loading
Regardless of the method of installing the toolkit, in order to use its functions,
the toolkit must be loaded using the pkg load command:

@example
pkg load instrument-control
@end example

The toolkit must be loaded on each @acronym{GNU} Octave session.

@c -------------------------------------------------------------------------
@node Basic Usage Overview
@chapter Basic Usage Overview
@cindex Basic Usage Overview

@node  Authors
@section  Authors
The Instrument control package provides low level I/O functions for serial, i2c, spi, parallel, tcp, gpib, vxi11, udp and usbtmc interfaces.

It was written  mainly by the following developers:

@itemize
@item Andrius Sutas <andrius.sutasg at mail.com>
@item Stefan Mahr <dac922 at gmx.de>
@item John Donoghue <john.donoghue at ieee.org>
@end itemize

@node  Available Interface
@section  Available Interfaces
The ability to use each interface is dependent on OS and what libraries were available during the toolkit install.

To verify the available interfaces, run the following command in octave:

@example
instrhwinfo
@end example

The function will return information on the supported interfaces that are available, similar to below:

@example
    ToolboxVersion = 0.7.0
    ToolboxName = octave instrument control package
    SupportedInterfaces =
    @{
      [1,1] = gpib
      [1,2] = i2c
      [1,3] = parallel
      [1,4] = serial
      [1,5] = serialport
      [1,6] = tcp
      [1,7] = tcpclient
      [1,8] = udp
      [1,9] = udpport
      [1,10] = usbtmc
      [1,11] = vxi11
    @}
@end example

Most interfaces have two types of functions:

@itemize
@item somewhat compatible matlab functions such as fread, fwrite

@item interface specific lower level functions such as udp_read, udp_write
@end itemize


@node  Basic Serial
@section  Basic Serial

@subsection Serial
@boxnote{The serial object has been deprecated and may not appear in newer versions of the instrument-control toolbox. Instead new code should use the serialport object.}

The serial port can be opened using the serial function:

@example
s = serial("/dev/ttyUSB1", 115200) 
@end example

The first parameter is the device name and is OS specific. The second parameter is the baudrate. 

A list of available serial ports can be retrieved using the function:

@example
seriallist
@end example

After creating the interface object, properties of the device can be set or retrieved using get or set functions or as property access.

@example
s = serial("/dev/ttyUSB1", 115200) 
br = get(s, "baudrate") # gets the baudrate
br = s.baudrate  # also gets the baudrate

set(s, "baudrate", 9600) # set the baudrate
s.baudrate = 9600 # also sets the baudrate
@end example

The device can be written and read from using fread, fwrite and srl_read and slr_write functions.

@example
srl_write(s, "hello world") # write hello world
fprintf(s, "hello again")

val = srl_read(s, 10) # attempt to read
val = fread(s, 10)
@end example

The device can be closed using fclose or srl_close.

@example
fclose(s)
@end example

@subsection SerialPort

The recommended method of accessing serial ports is through the serialport object.

The serial port can be opened using the serialport function:

@example
s = serialport("/dev/ttyUSB1", 115200) 
@end example

The first parameter is the device name and is OS specific. The second parameter is the baudrate. 

A list of available serial ports can be retrieved using the function:

@example
serialportlist
@end example

After creating the interface object, properties of the device can be set or retrieved using get or set functions or as property access.

@example
s = serialport("/dev/ttyUSB1", 115200) 
br = get(s, "BaudRate") # gets the baudrate
br = s.BaudRate  # also gets the baudrate

set(s, "BaudRate", 9600) # set the baudrate
s.BaudRate = 9600 # also sets the baudrate
@end example

The device can be written and read from using read and write functions.

@example
write(s, "hello world") # write hello world

val = read(s, 10)
@end example

The device can be closed by clearing the serialport object.

@example
clear s
@end example

@node  Basic TCP
@section  Basic TCP

@subsection TCP
@boxnote{The TCP object has been deprecated and may not appear in newer versions of the instrument-control toolbox. Instead new code should use the tcpclient object.}

A TCP connection can be opened using the tcp or tcpip function:

@example
s = tcp("127.0.0.1", 80) 
@end example

The first parameter is the IP address to connect to. The second parameter is the port number. And optional timeout value can be also be provided.

A more matlab compatible function is available as tcpip to also open a tcp port:

@example
s = tcpip("gnu.org", 80) 
@end example

The first  parameter is a hostname or ip address, the second the port number. Additional parameter/value pairs can be provided after the port.


After creating the interface object, properties of the device can be set or retrieved using get or set functions or as property access.

@example
s = tcp("127.0.0.1", 80)
oldtimeout = get(s, "timeout") # get timeout

set(s, "timeout", 10) # set the timeout
s.timeout = oldtimeout # also sets the timeout
@end example

The device can be written and read from using fread, fwrite and tcp_read and tcp_write functions.

@example
tcp_write(s, "HEAD / HTTP/1.1\r\n\r\n")

val = tcp_read(s, 100, 500) # attempt to read 100 bytes
@end example

The device can be closed using fclose or tcp_close.

@example
fclose(s)
@end example

@subsection TCP Client

The recommended method of creating a tcp connection is through the tcpclient object.

A TCP connection can be opened using the tcpclient function:

@example
s = tcpclient("127.0.0.1", 80) 
@end example

The first parameter is the IP address or hostname to connect to. The second parameter is the port number.

Additional parameter/value pairs can be provided after the port.

After creating the interface object, properties of the device can be set or retrieved using get or set functions or as property access.

@example
s = tcpclient("127.0.0.1", 80)
oldtimeout = get(s, "Timeout") # get timeout

set(s, "Timeout", 10) # set the timeout
s.Timeout = oldtimeout # also sets the timeout
@end example

The device can be written and read from using read and write functions.

@example
write(s, "HEAD / HTTP/1.1\r\n\r\n")

val = read(s, 100) # attempt to read 100 bytes
@end example

The device can be closed by clearing the object variable.

@example
clear s
@end example

@node  Basic UDP
@section  Basic UDP

@subsection UDP
@boxnote{The UDP object has been deprecated and may not appear in newer versions of the instrument-control toolbox. Instead new code should use the udpport object.}

A UDP connection can be opened using the udp function:

@example
s = udp("127.0.0.1", 80) 
@end example

The first parameter is the IP address data will be to. The second parameter is the port number. 

If and ip address and port is not provides, it will default to "127.0.0.1" and 23.

The address and port can be changed after creation using the remotehost and remoteport properties.

@example
s = udp() 
s.remotehost = "127.0.0.1";
s.remoteport = 100;
@end example

After creating the interface object, other properties of the device can be set or retrieved using get or set functions or as property access.

@example
s = udp("127.0.0.1", 80)
oldtimeout = get(s, "timeout") # get timeout

set(s, "timeout", 10) # set the timeout
s.timeout = oldtimeout # also sets the timeout
@end example

The device can be written and read from using fread, fwrite and udp_read and udp_write functions.

@example
udp_write(s, "test")

val = udp_read(s, 5)
@end example

The device can be closed using fclose or udp_close.

@example
fclose(s)
@end example

@subsection UDP Port

The recommended method of creating a udp socket is through the udpport object.

A udpport object can be created using the udpport function:

@example
s = udpport()
@end example

Additional parameter/value pairs can be provided during creation of the object.

After creating the interface object, properties of the device can be set or retrieved using get or set functions or as property access.

@example
s = udpport()
oldtimeout = get(s, "Timeout") # get timeout

set(s, "Timeout", 10) # set the timeout
s.Timeout = oldtimeout # also sets the timeout
@end example

The device can be written and read from using read and write functions.

The destination address and port to send data to must be specified at least on the first time write is used.

@example
write(s, "test", "127.0.0.1", s.LocalPort)

val = read(s)
@end example

The device can be closed by clearing the object variable.

@example
clear s
@end example

@c -------------------------------------------------------------------------
@node Function Reference
@chapter Function Reference
@cindex Function Reference

The functions currently available in the toolkit are described below.

@include functions.texi

@c -------------------------------------------------------------------------

@include gpl.texi

@c -------------------------------------------------------------------------
@node Index 
@unnumbered Index 
 
@printindex cp
 
@bye