NAME
IO::HyCon - Perl interface to the Analog Paradigm hybrid controller.
VERSION
This document refers to version 0.5 of HyCon
SYNOPSIS
use strict;
use warnings;
use File::Basename;
use HyCon;
(my $config_filename = basename($0)) =~ s/\.pl$//;
print "Create object...\n";
my $ac = HyCon->new("$config_filename.yml");
$ac->set_ic_time(500); # Set IC-time to 500 ms
$ac->set_op_time(1000); # Set OP-Time to 1000 ms
$ac->single_run(); # Perform a single computation run
# Read a value from a specific computing element:
my $element_name = 'SUM8-0';
my $value = $ac->read_element($element_name);DESCRIPTION
This module implements a simple object oriented interface to the Arduino based Analog Paradigm hybrid controller which interfaces an analog computer to a digital computer and thus allows true hybrid computation.
Functions and methods
new($filename)
This function generates a HyCon-object. Currently there is only one hybrid controller supported, so this is, in fact, a singleton and every subsequent invocation will cause a fatal error. This function expects a path to a YAML configuration file of the following structure:
config.yml:
serial:
port: /dev/tty.usbmodem621
bits: 8
baud: 250000
parity: none
stopbits: 1
poll_interval: 1000
poll_attempts: 200
builtin_dpt:
values: .1, .2, .3, .4, .5, .6, .7, .8
types:
0: PS
1: SUM8
2: INT4
3: PT8
4: CU
5: MLT8
6: MDS2
7: CMP4
8: HC
elements:
Y_DDOT: 0x0100
Y_DOT: 0x0101
PT_8-0: 0x0220
PT_8-1: 0x0221
PT_8-2: 0x0222
PT_8-3: 0x0223
PT_8-4: 0x0224
PT_8-5: 0x0225
PT_8-6: 0x0226
PT_8-7: 0x0227
manual_potentiometers:
PT_8-0,rT_8-1,PT_8-2,PT_8-3,PT_8-4,PT_8-5,PT_8-6,PT_8-7The setup shown above will not fit your particular analog computer configuration, it just serves as an example. The remaining parameters nevertheless apply in general and are mostly self-explanatory. 'poll_interval' and 'poll_attempts' control how often this interface will poll the hybrid controller to get a response to a command issued before. The values shown above are overly pessimistic but won't hurt during normal operation.
The section labeled 'builtin_dpt' contains data to setup and control the built-in digital potentiometers of the hybrid controller (currently only eight such potentiometers are supported by the hardware). The initial values of these potentiometers can be specified by a list containing eight entries following the key 'values'. If this part is missing, initial values of 0 are assumed. The new() function will set all digitally controlled potentiometers of the hybrid computer according to these values upon invocation.
If the number of values specified in the array 'values' does not match the number of configured potentiometers, the function will abort.
The 'types' section contains the mapping of the devices types as returned by the analog computer's readout system to their module names. This should not be changed but will be expanded when new analog computer modules will be developed.
The 'elements' section contains a list of computing elements defined by an arbitrary name and their respective address in the computer system. Calling read_all_elements() will switch the computer into HALT-mode, read the values of all elements in this list and return a reference to a hash containing all values and IDs of the elements read. (If jitter during readout is to be minimized, a readout-group should be defined instead, see below.)
Ideally, all manual potentiometers are listed under 'manual_potentiometers' which is used for automatic readout of the settings of these potentiometers by calling read_mpts(). This is useful if a simulation has been parameterized manually and these parameters are required for documentation purposes or the like. Caution: All potentiometers to be read out by read_mpts() must be defined in the elements-section.
The new() function will clear the communication buffer of the hybrid controller by reading and discarding and data until a timeout will be reached. This currently equals the product of 'poll_interval' and 'poll_attempts' and may take a few seconds during startup.
get_response()
In some cases, e.g. external HALT conditions, it is necessary to query the hybrid controller for any messages which may have occured since the last command. This can be done with this method - it will poll the controller for a period of 'poll_interval' times 'poll_attemps' microseconds. If this timeout value is not suitable, a different value (in milliseconds) can be supplied as first argument of this method. If this argument is zero or negative, get_response will wait indefinitely for a response from the hybrid controller.
ic()
This method switches the analog computer to IC (initial condition) mode during which the integrators are (re)set to their respective initial value. Since this involves charging a capacitor to a given value, this mode should be activated for the a minimum duration as required by the time scale factors involved.
ic() and the two following methods should not be used when timing is critical. Instead, IC- and OP-times should be setup explicitly (see below) and then a single-run should be initiated which will be under control of the hybrid controller. This avoids latencies involved with the communication to and from the hybrid controller and allows sub-millisecond resolution.
op()
This method switches the analog computer to operating-mode.
halt()
Calling this method causes the analog computer to switch to HALT-mode. In this mode the integrators are halted and store their last value. After calling halt() it is possible to return to OP-mode by calling op() again. Depending on the analog computer being controlled, there will be a more or less substantial drift of the integrators in HALT-mode, so it is advisable to keep the HALT-periods as short as possible to minimize errors.
A typical operation cycle may look like this: IC-OP-HALT-OP-HALT-OP-HALT. This would start a single computation with the possibility of reading values from the analog computer during the HALT-intervals.
Another typical cycle is called 'repetitive operation' and looks like this: IC-OP-IC-OP-IC-OP... This is normally used with the integrators set to time-constants of 100 or 1000 and allows to display a solution as a more or less flicker free curve on an oscilloscope for example.
enable_ovl_halt()
During a normal computation on an analog computation there should be no overloads of summers or integrators. Such overload conditions are typically the result of an erroneous computer setup (normally caused by wrong scaling of the underlying equations). To catch such problems it is usually a good idea to switch the analog computer automatically to HALT-mode when an overload occurs. The computing element(s) causing the overload condition can the easily identified on the analog computer's console and the variables of the computation run can be read out to identify the cause of the problem.
disable_ovl_halt()
Calling this method will disable the automatic halt-on-overload functionality of the hybrid controller.
enable_ext_halt()
Sometimes it is necessary to halt a computation when some condition is satisfied (some value reached etc.). This is normally detected by a comparator used in the analog computer setup. The hybrid controller features an EXT-HALT input jack that can be connected to such a comparator. After calling this method, the hybrid controller will switch the analog computer from OP-mode to HALT as soon as the input signal patched to this input jack goes high.
disable_ext_halt()
This method disables the HALT-on-overflow feature of the hybrid controller.
single_run()
Calling this method will initiate a so-called 'single-run' on the analog computer which automatically performs the sequence IC-OP-HALT. The times spent in IC- and OP-mode are specified with the methods set_ic_time() and set_op_time() (see below).
It should be noted that the hybrid controller will not be blocked during such a single-run - it is still possible to issue other commands to read or set ports etc.
single_run_sync()
This function behaves quite like single_run() but waits for the termination of the single run, thus blocking any further program execution. This method returns true if the single-run mode was terminated by an external halt condition. undef is returned otherwise.
repetitive_run()
This initiates repetitive operation, i.e. the analog computer is commanded to perform an IC-OP-IC-OP-... sequence. The hybrid controller will not block during this sequence. To terminate a repetitive run, either ic() or halt() may be called. Note that these methods act immediately and will interrupt any ongoing IC- or OP-period of the analog computer.
pot_set()
This function switches the analog computer to POTSET-mode i.e. the integrators are set implicitly to HALT, while all (manual) potentiometers are connected to +1 on their respective input side. This mode can be used to read the current settings of the potentiometers.
set_ic_time($milliseconds)
It is normally advisable to let the hybrid controller take care of the overall timing of OP and IC operations since the communication with the digital host introduces quite some jitter. This method sets the time the analog computer will spend in IC-mode during a single- or repetitive run. The time is specified in milliseconds and must be positive and can not exceed 999999 milliseconds due to limitations of the hybrid controller firmware.
set_op_time($milliseconds)
This method specifies the duration of the OP-cycle(s) during a single- or repetitive analog computer run. The same limitations hold with respect to the value specified as for the set_ic_time() method.
read_element($name)
This function expects the name of a computing element specified in the configuation YML-file and applies the corresponding 16 bit value $address to the address lines of the analog computer's bus system, asserts the active-low /READ-line, reads one value from the READOUT-line, and de-asserts /READ again. read_element(...) returns a reference to a hash containing the keys 'value' and 'id'.
read_element_by_address($address)
This function expects the 16 bit address address of a computing element as parameter and returns a data structure identically to that returned by read_element. This routine should not be used in general as computing elements are better addressed by their name. It is mainly provided for completeness.
read_all_elements()
The routine read_all_elements() reads the current values from all elements listed in the 'elements' section of the configuration file. It returns a reference to a hash containing all elements read with their associated values and IDs. It may be advisable to switch the analog computer to HALT mode before calling read_all_elements() to minimize the effect of jitter. After calling this routine the computer has to be switched back to OP mode again. A better way to readout groups of elements is by means of a readout-group (see below).
set_ro_group()
This function defines a readout group, i.e. a group of computing elements specified by their respective names as defined in the configuration file. All elements of such a readout group can be read by issuing a single call to read_ro_group() thus reducing the communications overhead between the HC and digital computer substantially. A typical call would look like this (provided the names are defined in the configuration file):
$ac->set_ro_group('INT0_1', 'SUM2_3');read_ro_group()
read_ro_group() reads all elements defined in a readout group. This minimizes the communications overhead between digital and analog computer and reduces the effect of jitter during readout as well as the risk of a serial line buffer overflow on the side of the hybrid controller. The function returns a reference to a hash containing the names of the elements forming the readout group with their associated values.
read_digital()
In addition to these analog readout capabilities, the hybrid controller also features eight digital inputs which can be used to read the state of comparators or other logic elements of the analog computer being controlled. This method returns an array-reference containing values of 0 or 1 for each of the digital input ports.
digital_output($port, $value)
The hybrid controller also features eight digital outputs which can be used to control the electronic switches which are part of the comparator unit. Calling digital_output(0, 1) will set the first (0) digital output to 1 etc.
read_mpts()
Calling read_mpts() returns a reference to a hash containing the current settings of all manual potentiometers listed in the 'manual_potentiometers' section in the configuration file. To accomplish this, the analog computer is switched to POTSET-mode (implying HALT for the integrators). In this mode, all inputs of potentiometers are connected to the positive machine unit +1, so that their current setting can be read out. ("Free" potentiometers will behave erroneously unless their second input is connected to ground, refer to the analog computer manual for more information on that topic.)
set_pt($address, $value)
To set a digital potentiometer, set_pt() is called. The first argument is the address of the potentiometer to be set (0 <= number < number-of-potentiometers as specified in the potentiometers section in the configuration YML-file), the second argument is a floatingpoint value 0 <= v <= 1. If either the address or the value is out of bounds, the function will die.
get_status()
Calling get_status() yields a reference to a hash containing all current status information of the hybrid controller. A typical hash structure returned may look like this:
$VAR1 = {
'IC-time' => '500',
'MODE' => 'HALT',
'OP-time' => '1000',
'STATE' => 'NORM',
'OVLH' => 'DIS',
'EXTH' => 'DIS',
'RO_GROUP' => [..., ..., ...]
};In this case the IC-time has been set to 500 ms while the OP-time is set to one second. The analog computer is currently in HALT-mode, and the hybrid controller is in its normal state, i.e. it is not currently performing a single- or repetitive-run. HALT on overload and external HALT are both disabled. A readout-group has been defined, too.
get_op_time()
In some applications it is useful to be able to determine how long the analog computer has been in OP-mode. As time as such is the only free variable of integration in an analog-electronic analog computer, it is a central parameter to know. Imagine that some integration is being performed by the analog computer and the time which it took to reach some threshold value is of interest. In this case, the hybrid controller would be configured so that external-HALT is enabled. Then the analog computer would be placed to IC-mode and then to OP-mode. After an external HALT has been triggered by some comparator of the analog commputer, the hybrid controller will switch the analog computer to HALT-mode immediately. Afterwards, the time the analog computer spent in OP-mode can be determined by calling this method. The time will be returned in microseconds (the resolution is about +/- 3 to 4 microseconds).
reset()
The reset() method resets the hybrid controller to its initial setup. This will also reset all digital potentiometer settings including their number! During normal operations it should not be necessary to call this method which was included primarily to aid debugging.
set_address(address)
set_address() is used to set the hybrid controller to a different address than its default address of 0x0090. The hybrid controller requires its own address on the backplane in order to set the builtin digital potentiometers. If the controller is placed into another slot than the last one of the main backplane (something which is not recommended), then this method has to be called before any changes to the builtin digitally controlled potentiometer setting are made. If the hybrid controller's address is not set correctly setting the digital potentiometers will fail silently! The address has to be specified in hexadecimal notation with four digits (padded on the left with zeros if necessary).
Examples
The following example initates a repetitive run of the analog computer with 20 ms of operating time and 10 ms IC time:
use strict;
use warnings;
use File::Basename;
use HyCon;
(my $config_filename = basename($0)) =~ s/\.pl$//;
my $ac = HyCon->new("$config_filename.yml");
$ac->set_op_time(20);
$ac->set_ic_time(10);
$ac->repetitive_run();AUTHOR
Dr. Bernd Ulmann, ulmann@analogparadigm.com