Package: cfcapi
cfcapiPythonAPI to interact with the Caonabo Fluidic Controller (CFC).
The CFC is a board that allows one to control a total of 50 valves to manipulate the flow of chemicals.
It is composed of five valve modules and one control module. Each valve module is composed of the following peripherals:Darlington open collector transistor outputs with flyback protection diodes for controlling valves (10)Input / output TTL (5.0V) digital ports (5)Module indicator LED (1)From the 10 valve outputs of each valve module, 6 of them (from index 0 to 5) can drive valves of up to 0.5A,
the remaining 4 (6 to 9) can handle up to 1A. All of them can handle up to 50V.The control module is built around an Arduino Nano 33 BLE module and is composed of the following peripherals:Input / output CMOS (3.3V) digital ports (10)Analog (0V to 3.3V) inputs  (7)Module indicator RGB LED (1)This API allows the manipulation of all these peripherals inPython. For more information regarding the CFC hardware please visit itsrepository.Table of contentsInstallation and package dependenciesHow to use the package2.1 Instantiation, initiation and closing comunication to the board.2.2 Working with digital Input/Ouput (IO) ports and analog ports.2.3 Working with valves.API reference guideContributorsLicense1 Installation and package dependenciesThis packager requires the previous installation of the following packages:pyserial 3.5 (or newer)Afer installing the dependencies, the package can be installed from the Python package index (PyPI) repository.In Windows:C:\>pipinstall--usercfcapior in Linux:$pipinstall--usercfcapiAs an alternative, the cfcapi package (inside thesrc/folder) can be download and copied into the the main folder of the project where it will be used.2 How to use the package2.1 Instantiation, initiation and closing communication to the board.First, the module must be imported:>>>fromcfcapiimportboardOnce imported the cfc class inside the module must be instantatiated to gain control to an specific CFC board.
Hence, the port where the CFC board is connected, as well as the ID of the board, must be specified.
For the port, the name of the port can be given such as"COM1"or"AUTO"can be used.
Sometimes,"AUTO"might not work due to conflict with some USB devices.
If this happens, the port will have to be passed manually. An example instantiations can be as folows:>>>cfc=board.cfc(port="AUTO",board_id="000")Once initiated, the following output will appear in the console:Caonabo Fluidic Controller (CFC) with correct ID initiated in port: COM26.CFC Modules addresses: ['2', '3', '4', '5', '6']The last line identifies the addresses of the 5 different valve modules (from 0 to 4),
and should agree with the physical address configured for each module with the DIP switches.
If this does not match, communication with that module will fail.
To test that the communication to each module works the thetestModule()method can be used.
For example:>>>cfc.testModules()TheModule indicator LEDsof each module will turn on for 0.5s sequentially from module 0 to module 4.
If the communication to any of the module fails, the respective LED will not be turned on.
The first thing to check while debugging a possible problem is the that the physical address (set with the DIP switch)
matches with that of the firmware (the one shown when instantiating or when using the methodgetAddress()).At the end, the instance must be properly closed to avoid leaving the serial ports open. This is done by using theclose()method:>>>cfc.close()2.2 Working with digital input/ouput (IO) ports and analog ports.For working the IO ports, they first have to be configured.
By default, the digital ports of the modules (pin 10 to 14 of pin header) are configured asinputs.
The index for addressing the IOs of the modules is from 0 to 4 linked to physical pins 10 to 14.
The IOs of the Arduino module (D2 to D10) are also initiated asinputs.
The indexes to address the IOs from the Arduino module runs from 2 to 10.To configurethe IO ports, the methodconfIO(mode_list, module)must be used.
The first parameter required is a list of integers that represents whether the pin will act as an input (0) or an output (1).
The amount of elements in the list should match the amount of IOs in the port to be configured (i.e., 5 for the valve modules and 9 for the Arduino module).
The second parameter is the module: for valve modules a value between0to4(integer) can be used,
and for the Arduino module the"A"character must be used.
By default (i.e., if no module value is passed) the Arduino module is selected.
To configure the first three (0, 1 and 2) IO ports of module 0 as outputs, and the last two (3 and 4) as inputs the following example can be used:>>>cfc.confIO(mode_list=[1,1,1,0,0],module=0)To configure all the IOs of the Arduino module (D2 to D10) as outputs, the following example can be used:>>>cfc.confIO(mode_list=[1,1,1,1,1,1,1,1,1],module="A")Once configured, the IO port can bewritenby using the methodwriteIO(ioNumber, value, module),
orreadusing the methodreadIO(ioNumber, module).
The parameterioNumberis the number identifying the IO (from 0 to 4 for valve modules and from 2 to 10 for Arduino module).
The value parameter (only for writing) specify whether the IO port will be 1 (5V for valve modules and 3.3V for Arduino module) or 0 (GND for all modules).
Finally, the module parameter (0 to 4 or "A") will identify the module to which the IO belongs.
For example, to write 1 to IO 0 of module 0 you can use:>>>cfc.writeIO(ioNumber=0,value=1,module=0)and to read from IO D9 of the Arduino module can use:>>>cfc.readIO(ioNumber=9,module="A")`or`>>>cfc.readIO(ioNumber=9)Theanalogports in the Arduino module (A0 to A6) can bereadusing the methodanalogRead(aNumber).
TheaNumberparmeter is simply the number of the analog port to be read (from0to6).
The method returns a value between 0 and 1023, proportional to the voltage in the respective port (from 0 to 3.3v).2.3 Working with valves.Toset a valveoutput the methodsetValve(valve)must be used, and toto clear a valvethe methodclearValve(valve)must be used.
Thevalveparameter is value from0to49identifiying the valve.
The first digit in the number identifies the module and second digit identifies the valve.
For example, valve45is valve with index5on module with index4.
Similarly, valve3(same as03) identifies the valve with index3in module with index0.
For example, setting and clearing valve 3 of module 2 can be done with:>>>cfc.setValve(23)and>>>cfc.clearValve(23)Additionally, the valves can beactivated with a pulsewith the methodpulse(valve, tON, tOFF, periods).
Thevalveparameter is the same as for the previous methods, wheretONandtOFFare use to specify
the amount of time (in seconds) that the valve will remain on and off, respectively. ParametertOFFis set to0.
The last parameterperiodsis use to define how many times the cycletONandtOFmust be repeated.
By default,periodsis set to 1.
If it is desired to set on valve 23 for one second the following code can be used:>>>cfc.pulse(valve=23,tON=1,tOFF=0,periods=1)or>>>cfc.pulse(valve=23,tON=1)3 API Reference GuideMethodDescriptionParametersReturnsExample00getIDReturns the ID of the CFC board.NAID (string)cfc.getID()01getAddressReturns the address of the modules configured in the firmware.NAaddresses (list of strings)cfc.getAddress()02rgbLEDSet status of the RGB LED in the Arduino nano 33 BLE board ON (1) or OFF (0).r, g, b (int)NAcfc.rgbLED(0,1,0)03confIOConfigures the IO ports available in either the arduino or the valve modules.mode_list (str), module="A" (str or int)NAcfc.confIO("11100",0)04writeIOWrite to the IO ports of the Arduino or the valve modules.ioNumber (int), value (int - 0 or 1), module="A" (int of str)NAcfc.writeIO(3,1,"A")05readIORead the digital ports of the Arduino, or the valve modules.ioNumber (int), module="A" (int of str)value (int - 0 or 1)cfc.readIO(3,"A")06analogReadRead the analog ports of the Arduino.ZINis 108ohm.aNumber (int)value (int - 0 to 1023)cfc.analogRead(2)07moduleLEDManipulate the LEDs in the different valve modules of the CFC.module, value (int)NAcfc.moduleLED(0,1)08setValveSet a valve on the CFC. The value can go from 0 to 49.valve (int)NAcfc.setValve(15)09clearValveClear a valve on the CFC. The value can go from 0 to 49.valve (int)NAcfc.clearValve(15)10pulseCreate a tren of pulses activating one of the valves.valve, tON, tOFF=0, periods=1 (int)NAcfc.pulse(15,1,0,1)11testModulesActivate the LED on the modules sequentially. The LED remains ON for t seconds.t=0.5 (float)NAcfc.testModules()12discoverPortDiscover the USB port to which the CFC is connected.NAport (str)cfc.discoverPort()13comStart serial communication with the CFC. Runs once during instantiation.port="NA" (str), bit_rate="NA" (str or int), board_id="NA" (str), timeout="NA" (Str or float)NAcfc.com("COM4",115200, "000", 1)14writeWrite string of characters to the CFC through the serial bus.string (str)response (str)cfc.write("ID?")15readRead string of characters from the CFC through the serial bus.NAresponse (str)cfc.read()16acknowledgeWriteCheck for the acknowledgement response from the CFC after writing a command that does not require a return from the CFC.NANAcfc.acknowledgeWrite()17closeMethod to close the communication to the CFC.NANAcfc.close()18openMethod to open communication to the CFC.NANAcfc.open()4 ContributorsCésar Javier Lockhart de la Rosa (lockhart@imec.be)Kherim Willems (kherim.willems@imec.be)Naghmeh Fatemi (naghmeh.fatemi.ext@imec.be)5 LicenseCopyright (c) 2022César J. Lockhart de la Rosa (lockhart@imec.be)Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.