Changes

Jump to navigation Jump to search
Fix copy-paste error in comment
Line 1: Line 1: −
Instrument-Control is a package for interfacing the outside world of hardware via Serial, i2c or Parallel interfaces. It is currently under development by Andrius Sutas, you can browse the SVN [http://svn.code.sf.net/p/octave/code/trunk/octave-forge/main/instrument-control/ repository here].
+
Instrument-Control is a package for interfacing the outside world of hardware via Serial, i2c or Parallel interfaces. It is currently under development by Andrius Sutas and Stefan Mahr, you can browse the [https://sourceforge.net/p/octave/instrument-control/ci/default/tree/ mercurial repository here] and download the package [http://octave.sourceforge.net/instrument-control/index.html here].
 +
 
 +
= Compatibility =
 +
 
 +
Below is a table showing package compatibility with various platforms:
 +
 
 +
{| class="wikitable" style="text-align:center"
 +
|-
 +
!  !! Linux                !! Windows (Cygwin)        !! Windows (native)        !! FreeBSD                !! Mac OS X
 +
|-
 +
! Serial
 +
| bgcolor="green" | v0.1.0 || bgcolor="green" | v0.2.0 || bgcolor="green" | v0.2.1 || bgcolor="skyblue" | stalled || bgcolor="green" | v0.2.2
 +
|-
 +
! Parallel
 +
| bgcolor="green" | v0.1.0 || -                        || -                        || bgcolor="skyblue" | stalled || -
 +
|-
 +
! i2c
 +
| bgcolor="green" | v0.1.0 || -                        || -                        || bgcolor="skyblue" | stalled || -
 +
|-
 +
! spi
 +
| bgcolor="green" | v0.6.0 || -                        || -                        || -                          || -
 +
|-
 +
! TCP
 +
| bgcolor="green" | v0.2.0 || bgcolor="green" | v0.2.0 || bgcolor="green" | v0.2.0 || bgcolor="skyblue" | stalled ||  bgcolor="green" | v0.2.2
 +
|-
 +
! UDP
 +
| bgcolor="green" | v0.3.0 || bgcolor="green" | v0.3.0 || bgcolor="green" | v0.3.0 || -                        || bgcolor="green" | v0.3.0
 +
|-
 +
! USBTMC
 +
| bgcolor="green" | v0.2.0 || -                        || -                        || -                        ||  -
 +
|-
 +
! GPIB
 +
| bgcolor="green" | v0.2.0 [[#Linux|(*)]] || bgcolor="green" | v0.2.0 [[#Windows_.28cygwin.29|(*)]] || - ||- ||  -
 +
|-
 +
! VXI11
 +
| bgcolor="green" | v0.2.0|| bgcolor="green" | v0.2.0 [[#Windows_.28cygwin.29|(*)]] || - || - || bgcolor="yellow" | WIP [[#MacOS|(*)]]
 +
|}
 +
 
 +
Where: <span style="background:green">(VER)</span> - Included since VER version; <span style="background:yellow">(WIP)</span> - Work In Progress and will probably be included in next release; <span style="background:skyblue">(stalled)</span> - Some work has been done, but it's not tested and no one is actively contributing; (-) - Not supported / Untested.
 +
 
 +
You might see errors while doing "pkg install", which mean that package is unable to support related interface on your platform (e.g. due to missing header files), therefore one should <b>always</b> check for the supported interfaces before trying to use them:
 +
 
 +
{{Code|Check for interface support|<syntaxhighlight lang="octave" style="font-size:13px">
 +
pkg load instrument-control
 +
supportedinterfaces = instrhwinfo().SupportedInterfaces
 +
 
 +
if ! isempty(strfind (supportedinterfaces , "serial"))
 +
    disp("Serial: Supported")
 +
else
 +
    disp("Serial: Unsupported")
 +
endif
 +
 
 +
#similarly with:
 +
# ! isempty(strfind (supportedinterfaces , "parallel"))
 +
# ! isempty(strfind (supportedinterfaces , "i2c"))
 +
</syntaxhighlight>}}
 +
 
 +
= Requirements =
 +
== Linux ==
 +
 
 +
For GPIB support, please install [http://linux-gpib.sourceforge.net linux-gpib] before installing instrument-control.
 +
 
 +
== Windows (cygwin) ==
 +
 
 +
For VXI11 support, please install 'rpcgen', 'libtirpc-devel', and 'libtirpc1' before installing instrument-control.
 +
 
 +
To be able to use GPIB on windows, the linux-gpib library needs to be 'faked'. This can be done by copying the following script and run it in a bash-terminal.
 +
 
 +
<syntaxhighlight lang="bash">
 +
#!/bin/bash
 +
# fake_linux_gpib.sh, Kire Pûdsje, Dec 2017
 +
 
 +
# This file generates a fake linux-gpib library on Windows, based on the
 +
# installed NI libraries.
 +
# Prerequisits are that during install of the NI drivers, the C/C++ support
 +
# and the NI Measurement & Automation explorer has been enabled.
 +
 
 +
# set the base for includes and libraries on your system
 +
# it is usually /usr, but on newer windows installs of octave, it will be
 +
# /mingw64
 +
INSTALL_BASE=/usr
 +
 
 +
# this define should find the NI header file, if properly installled
 +
# otherwise just point it to the proper header file.
 +
NI_H_FILE="${NIEXTCCOMPILERSUPP}/include/ni4882.h"
 +
NI_DLL_FILE=ni4882.dll
 +
NI_DEF_FILE=/tmp/${0##*/}-$$.def
 +
 
 +
# symlink NI header file
 +
mkdir -p ${INSTALL_BASE}/include/gpib/
 +
ln -sf "${NI_H_FILE}" ${INSTALL_BASE}/include/gpib/ib.h
 +
 
 +
# generate .def for all functions in the NI header file with a NI488CC prefix
 +
echo LIBRARY ${NI_DLL_FILE} > ${NI_DEF_FILE}
 +
echo EXPORTS >> ${NI_DEF_FILE}
 +
grep "NI488CC  *[A-Za-z]" ${INSTALL_BASE}/include/gpib/ib.h \
 +
  | sed "s/^.*NI488CC  *//" \
 +
  | sed "s/(.*$//" >> ${NI_DEF_FILE}
 +
 
 +
# generate the wrapper library simulating gpib-linux
 +
dlltool -d ${NI_DEF_FILE} -l ${INSTALL_BASE}/lib/libgpib.a
 +
 
 +
#cleanup
 +
rm -f ${NI_DEF_FILE}
 +
</syntaxhighlight>
 +
 
 +
== MacOS ==
 +
 
 +
You need to build '''rpcgen''' from source [http://mirror.ancl.hawaii.edu/pub/FreeBSD/FreeBSD-current/src/usr.bin/rpcgen].
 +
 
 +
If rpcgen cannot be build from source, the following error might be obtained:
 +
<syntaxhighlight lang="text"  style="font-size:13px">
 +
pkg: error running `make' for the instrument-control package.
 +
error: called from
 +
    configure_make at line 99 column 9
 +
    install at line 184 column 7
 +
    pkg at line 437 column 9
 +
</syntaxhighlight>
 +
 
 +
If the '''VXI-11 interface''' is not required, a workarround is proposed in [https://stackoverflow.com/questions/46720092/make-error-when-installing-instrument-control-package-for-octave/52860282#52860282] after the bug reported on [https://savannah.gnu.org/bugs/?54842].
    
= Examples =
 
= Examples =
Line 18: Line 137:  
do not forget to change interface permissions if you want to use them with Octave/screen without root privileges.
 
do not forget to change interface permissions if you want to use them with Octave/screen without root privileges.
   −
=== Example ===
+
=== Example: basic use ===
 
Here is a simple example to get started with the serial package. It tests the RxD and TxD lines. Make sure you have defined a loopback or connected the pins of your adapter.
 
Here is a simple example to get started with the serial package. It tests the RxD and TxD lines. Make sure you have defined a loopback or connected the pins of your adapter.
 
{{Code|Serial port example|<syntaxhighlight lang="octave" style="font-size:13px">
 
{{Code|Serial port example|<syntaxhighlight lang="octave" style="font-size:13px">
# Open default serial port ttyUSB0 in default configuration of 115200, 8-N-1
  −
s0 = serial()
   
# Opens serial port ttyUSB1 with baudrate of 115200 (config defaults to 8-N-1)
 
# Opens serial port ttyUSB1 with baudrate of 115200 (config defaults to 8-N-1)
 
s1 = serial("/dev/ttyUSB1", 115200)  
 
s1 = serial("/dev/ttyUSB1", 115200)  
Line 36: Line 153:  
}}
 
}}
   −
Chaging some configurations is simple done by calling helper functions
+
Changing some configurations is simply done by calling helper functions
 
{{Code|Serial port example: helper functions|<syntaxhighlight lang="octave" style="font-size:13px">
 
{{Code|Serial port example: helper functions|<syntaxhighlight lang="octave" style="font-size:13px">
srl_baudrate(s1, 9600) # Change baudrate
+
set(s1, "baudrate", 9600) # Change baudrate
srl_bytesize(s1, 5)    # Change byte size (config becomes 5-N-1)
+
set(s1, "bytesize", 5)    # Change byte size (config becomes 5-N-1)
srl_parity(s1, "E")    # Changes parity checking (config becomes 5-E-1),
+
set(s1, "parity", "E")    # Changes parity checking (config becomes 5-E-1),
                      # possible values [E]ven, [O]dd, [N]one.
+
                          # possible values [E]ven, [O]dd, [N]one.
srl_stopbits(s1, 2)    # Changes stop bits (config becomes 5-E-2), possible
+
set(s1, "stopbits", 2)    # Changes stop bits (config becomes 5-E-2), possible
                      # values 1, 2.
+
                          # values 1, 2.
 +
 
 +
set(s1, "dataterminalready", "on")  # Enables DTR line
 +
set(s1, "requesttosend", "on")      # Enables RTS line
 +
                                    # possible values "on", "off".
 +
 
 
</syntaxhighlight>
 
</syntaxhighlight>
 
}}
 
}}
Most properties can be set at opening time
+
Some properties can be set at opening time
 
{{Code|Serial port example: constructor call|<syntaxhighlight lang="octave" style="font-size:13px">
 
{{Code|Serial port example: constructor call|<syntaxhighlight lang="octave" style="font-size:13px">
s2 = serial("/dev/ttyS0", 9600, 6, "odd", 2) # Opens serial port ttyS0 in
+
s2 = serial("/dev/ttyS0", 9600, 10) # Opens serial port ttyS0 in
                                            # 9600, 6-O-2 configuration
+
                                    # 9600 baudrate with 1s read timeout
 
</syntaxhighlight>
 
</syntaxhighlight>
 
}}
 
}}
Line 55: Line 177:  
Do not forget to close the ports when you are done!
 
Do not forget to close the ports when you are done!
 
{{Code||<syntaxhighlight lang="octave" style="font-size:13px">
 
{{Code||<syntaxhighlight lang="octave" style="font-size:13px">
srl_close(s0) # Closes and releases file descriptor
+
fclose(s1) # Closes and releases serial interface object
srl_close(s1) # Closes and releases file descriptor
+
fclose(s2) # Closes and releases serial interface object
srl_close(s2) # Closes and releases file descriptor
+
</syntaxhighlight>
 +
}}
 +
 
 +
=== Example: Windows, serial port >COM9 ===
 +
Opening a serial port higher than COM9 requires special syntax. [https://support.microsoft.com/en-us/kb/115831]
 +
{{Code|open Windows higher serial port example|<syntaxhighlight lang="octave" style="font-size:13px">
 +
# Opens serial port COM10
 +
s1 = serial("\\\\.\\COM10");
 
</syntaxhighlight>
 
</syntaxhighlight>
 
}}
 
}}
Line 235: Line 364:     
== i2c ==
 
== i2c ==
i2c
+
Example with a Si7021 i2c breakout board (https://www.sparkfun.com/products/1376) connected to a i2c master interface.
 +
 
 +
To work out the devices available (assuming i2ctools are installed) run the i2cdetect command from a terminal window.
 +
 
 +
<syntaxhighlight lang="bash" style="font-size:13px">
 +
$ i2cdetect -l
 +
i2c-1  i2c            i2c-ch341-usb at bus 002 device 008    I2C adapter
 +
i2c-0  unknown        SMBus I801 adapter at 4000              N/
 +
</syntaxhighlight>
 +
 
 +
In the example case the temperature sensor is connected to the i2c-ch341-usb device, and it is assumed the user has sufficient permissions to access the device.
 +
 
 +
According to the datasheet, the temperature device uses address 0x40, so create a i2c device using the linux device and address:
 +
 
 +
<syntaxhighlight lang="octave" style="font-size:13px">
 +
i2cdev = i2c("/dev/i2c-1", 0x40)
 +
</syntaxhighlight>
 +
 
 +
To read  the temperature, register 0xF3 must be addressed and read (2 bytes of data):
 +
 
 +
<syntaxhighlight lang="octave" style="font-size:13px">
 +
TEMP_MEASURE_NOHOLD = hex2dec("F3");
 +
fwrite (i2cdev, uint8([TEMP_MEASURE_NOHOLD]));
 +
pause (0.02);
 +
data = fread (i2cdev, 3);
 +
</syntaxhighlight>
 +
 
 +
The data must be converted to a deg K value by making  16 bit number of the value and masking out unused bits.
 +
 
 +
<syntaxhighlight lang="octave" style="font-size:13px">
 +
value = uint16(data(1))*256 + uint16(data(2));
 +
value = bitand (value, hex2dec("FFFC"));
 +
temp_Code = double(value);
 +
</syntaxhighlight>
 +
 
 +
Now convert the temperature to degrees C and display:
 +
 
 +
<syntaxhighlight lang="octave" style="font-size:13px">
 +
C = (175.72*temp_Code/65536)-46.85;
 +
printf ("temperature read %f C\n", C);
 +
</syntaxhighlight>
 +
 
 +
== TCP ==
 +
=== Example: basic use ===
 +
For testing you could start a tcp listener
 +
<pre>
 +
$ socat TCP-LISTEN:8000 -
 +
</pre>
 +
 
 +
Now you can connect your listener.
 +
 
 +
{{Code|TCP example|<syntaxhighlight lang="octave" style="font-size:13px">
 +
# Open TCP connection to 127.0.0.1:8000
 +
t0 = tcp("127.0.0.1",8000)
 +
# write to listener
 +
tcp_write(t0, "Hello world!")
 +
# Blocking read call, returns uint8 array of exactly 12 bytes read
 +
data = tcp_read(t0, 12) 
 +
# Convert uint8 array to string,
 +
char(data)
 +
</syntaxhighlight>
 +
}}
 +
There are several ways to set timeout of read call.
 +
{{Code|set TCP timeout|<syntaxhighlight lang="octave" style="font-size:13px">
 +
# Open TCP connection to 127.0.0.1:8000 with timeout of 100 ms
 +
t0 = tcp("127.0.0.1",8000,100)
 +
# set timeout to blocking
 +
tcp_timeout(t0, -1)
 +
# the timeout can be overwritten for single read call, in this case 1000ms
 +
data = tcp_read(t0, 12, 1000) 
 +
# close tcp session
 +
tcp_close(t0)
 +
</syntaxhighlight>
 +
}}
 +
 
 +
== USBTMC ==
 +
=== Configuring interface ===
 +
Recent linux kernels support USBTMC out of the box. Connect your instrument and check if /dev/usbtmc* exists. Set appropriate permissions to /dev/usbtmc*
 +
=== Example: basic use ===
 +
{{Code|USBTMC example|<syntaxhighlight lang="octave" style="font-size:13px">
 +
# Open interface to USB instrument
 +
t0 = usbtmc('/dev/usbtmc0')
 +
# write to listener
 +
usbtmc_write(t0, '*IDN?')
 +
# Blocking read call, returns uint8 array
 +
data = usbtmc_read(t0, 10000) 
 +
# Convert uint8 array to string,
 +
char(data)
 +
# close usbtmc session
 +
usbtmc_close(t0)
 +
</syntaxhighlight>
 +
}}
 +
 
 +
== VXI11 ==
 +
=== Example: basic use ===
 +
{{Code|VXI11 example|<syntaxhighlight lang="octave" style="font-size:13px">
 +
# Open VXI11 connection to 192.168.100.100
 +
t0 = vxi11('192.168.100.100')
 +
# write to listener
 +
vxi11_write(t0, '*IDN?')
 +
# read from instrument, returns uint8 array
 +
data = vxi11_read(t0, 10000) 
 +
# Convert uint8 array to string,
 +
char(data)
 +
# close VXI11 session
 +
vxi11_close(t0)
 +
</syntaxhighlight>
 +
}}
 +
 
 +
=== Limitations ===
 +
For now,
 +
* it's not possible to connect more than one instrument per IP address (e.g. VXI11-GPIB gateways)
 +
* only instrument ''inst0'' can be connected
 +
* setting timeout is not implemented (defaults: 10 seconds global timeout, 2 seconds read timeout)
 +
 
 +
== GPIB ==
 +
=== Configuring interface ===
 +
For using GPIB you need to install and configure the linux-gpib kernel modules and libraries.
 +
=== Example: basic use ===
 +
{{Code|GPIB example|<syntaxhighlight lang="octave" style="font-size:13px">
 +
# Open GPIB instrument with ID 7 and set timeout to 1 second (see ibtmo / NI-488.2 Function Reference)
 +
t0 = gpib(7,11)
 +
# write to listener
 +
gpib_write(t0, '*IDN?')
 +
# read from instrument, returns uint8 array
 +
data = gpib_read(t0, 10000)
 +
# Convert uint8 array to string,
 +
char(data)
 +
# close usbtmc session
 +
gpib_close(t0)
 +
</syntaxhighlight>
 +
}}
 +
=== Limitations ===
 +
* Setting minor, sad, send_eoi and eos_mode is not implemented yet.
 +
* Every read or write command opens and closes a new gpib session, since the linux-gpib session pointer is only valid for single command.
 +
 
 +
== SPI ==
 +
=== Configuring interface ===
 +
SPI currently only works in linux.
 +
 
 +
instrhwinfo will display the avilable devices in the system
 +
 
 +
{{Code|SPI example|<syntaxhighlight lang="octave" style="font-size:13px">
 +
instrhwinfo("spi")
 +
</syntaxhighlight>
 +
}}
 +
 
 +
You will need read/write permissions to the device used.
 +
 
 +
=== Example: basic use ===
 +
Example opening an performing IO on a device /dev/spidev0.0.
 +
 +
{{Code|SPI example|<syntaxhighlight lang="octave" style="font-size:13px">
 +
# open device
 +
spidev = spi("/dev/spidev0.0", 'clockpolarity', 'idlehigh', 'clockphase', 'firstedge')
 +
 
 +
# I/O to device
 +
 
 +
data = writeAndRead (spidev, uint8([0x01 0x00]))
 +
 
 +
# close the device
 +
clear spidev
 +
</syntaxhighlight>
 +
}}
 +
 
   −
[[Category:OctaveForge]]
+
[[Category:Octave Forge]]
[[Category:Packages]]
 
Anonymous user

Navigation menu