Controlling the Korad KA3005P using Python

TL;DR: The protocol is simple, no start and termination of commands, plain ASCII over a serial port or the USB to serial bridge. The code presented is available on GitHub

Introduction

So after having used them at work for a few months I just had to get my own KA3005P bench-top lab power supply. Up until then I used some dumb (not controllable via serial port / USB / Ethernet) cheap bench-top power supplies that covered the same range as well as some custom home built supplies - and also still have the plan to build some switchmode supplies based on the TL494 by myself, especially for the high voltage regime. But since those supplies are rather affordable and their control is done simple via RS232 or an integrated USB to serial converter this had been the easier way to go for simple non specialized stuff.

The next step was to look into how those devices are controlled. There is some documentation available:

• For the fantastic sigrok project there is some documentation
• There are some discussions in the eevblog
• There are also some existing Python implementations around (which I didn’t use as a reference or basis, the described implementation is a cleanroom implementation without any existing codebase as usual)

Since the protocol is really pretty simple I started to implement my own library in ANSI C and in Python (I tend to use C99 for serious stuff and Python for playing around). To avoid designing APIs over and over again I also started a small collection of Python base classes for various laboratory devices such as power supplies, function generators, etc. - this will grow for sure - from which I then derive the implementations themselves so every new device will use exactly the same API as similar ones which allows one to simply swap devices.

The main reasons for a custom own implementation are the same as usual:

• Fully understanding what happens
• Really knowing the corner cases and how the library acts during failure
• Being responsible in case something goes wrong and understanding code to be able to fix it
• Having everything under my desired license, a 3 clause BSD license with advertising clause which is my preferred license for open source projects

The KA3005P is a standard linear power supply that support setting a target voltage as well as a current limit. It would also allow one to store different settings at four memory banks (I don’t make use of that - it’s mainly useful when you’re controlling the supply manually) and in addition to normal operation that one knows from other lab supplies it also support overcurrent and overvoltage “protection” modes in which triggering the voltage or current limit (constant voltage or constant current mode) disabled the output again which might be useful under some circumstances especially when testing circuits.

The KA3005P

The interfaces

The KA3005P support computer or microcontroller control via two different interfaces though only one can be active at the same time - there is a main serial port that runs on RS232 levels as well as an integrated USB to serial adapter that runs as a full speed (12 Mbps) USB device with the identification “Nuvoton USB Virtual COM”. It’s vendor ID is 0x0416, the product ID 0x5011 and announces itself as a communication device (CDC ACM). Under FreeBSD the stock kernel uses the umodem driver to supply an tty device one can use to communicate with the power supply when using the USB port.

On both interfaces the settings are:

• Baud rate 19200
• 8 data bits
• No parity bit
• One stop bit

In addition I usually define a short timeout of a second at most.

The power supply does not use any kind of robust serial communication such as a start pattern, a checksum or an end pattern. It seems to do simple pattern matching on the commands sent and usually one is required to know the length of the expected response to robustly decode it. Despite this the protocol seems to orient itself somewhat at SCPI (which also differs from device to device) there are no line endings, it’s really simple to implement using write and read from the serial port using pyserial or standard Unix file access methods.

The protocol

The following functions that I know of are supported by the KA3005P:

The status flags known to me are:

The Python library

TL;DR: The code is spread over two repositories:

• The abstract base classes are implemented in pylabdevs
• The actual implementation resides in pyka3005p

First I decided on the abstraction for power-supplies that I’d like to have and implemented those in my pylabdevs library as PowerSupply base class. The public functions that will later be used by applications are:

The init function is rather complex and allows one to specify the capabilities of the power supply:

• nChannels is an integer that tells the class how many channels are available. It’s assumed that all channels have the same capabilities
• vrange and arange specify voltage and current range, prange the supported power range. All three values require a tuple specifying minimum, maximum and supported step size (assumed to be constant over the full range)
• One can set capableVLimit and capableALimit to indicate if a power supply can work in constant voltage or constant current mode.
• capableMeasureV and capableMeasureA indicate if a powersupply is able to measure the actual voltage and current
• capableOnOff indicates if the powersupply can be enabled and disabled

All methods verify the supplied parameters already in the base class and are not overridden by the actual implementations. Note that voltage and current setters also verify if the maximum power range is exceeded or not with the desired setting and will raise an ValueError in this case.

The actual communication will be done by a set of private routines that are overridden by the actual classes and which do raise an NotImplementedError() in case they are called on the base class. Those are:

The setting methods usually should set a value and then read back the current setting from the device if supported to make sure it has been written correctly. It’s also assumed the implementations support using with by supplying an __enter__ and __exit__ routine. When exiting the context the power supply should turn off all outputs - the same goes for terminating the process which is usually realized using atexit even though the base class also implements calling _off() in an atexit routine itself.

In my own implementation in pyka3005p I’ve implemented the KA3005PSerial class that inherits from PowerSupply. There are two methods that handle the serial communication internally:

• _sendCommand is used to transmit the (ASCII string) command supplied without expecting any reply from the device.
• _sendCommandReply(cmd, replyLen = None) is used to transmit the (ASCII string) command supplied and expects the device to respond. The replyLen parameter specifies either a positive integer of the number of bytes expected (in case not enough bytes are received in the timeout window an IOError is raised). In case replyLen is set to None the method would expect a NULL terminated response which is actually not used in the implementation any more. Whenever a negative integer is supplied the method reads response bytes and assumes that a timeout indicates an end of the message - this is used for the identify response to the *IDN? command only.

In addition an internal __close method is implemented and registered as an atexit handler to tear down the serial port in case of an abnormal termination of in case a normal context exit is triggered.

This now allows pretty simple usage of the power supply using context routines or an imperative style:

from pyka3005p.ka3005pserial import KA3005PSerial

with KA3005PSerial("/dev/ttyU0") as psu:
	psu.setVoltage(5.00)
	psu.setCurrent(0.510)
	psu.setChannelEnable(True)

	measV, setV = psu.getVoltage()
	measA, setA = psu.getCurrent()

	print("Measured voltage {} V (set {} V)".format(measV, setV))
	print("Measured current {} A (set {} A)".format(measA, setA))

	sleep(10)

	psu.setChannelEnable(False)

Alternatively one can use the imperative style without context routines which is particularly useful for more complex scripts or Jupyter notebooks:

from pyka3005p.ka3005pserial import KA3005PSerial

psu = KA3005PSerial("/dev/ttyU0")

# One has to call connect ...
psu.connect()

psu.setVoltage(5.00)
psu.setCurrent(0.510)
psu.setChannelEnable(True)

measV, setV = psu.getVoltage()
measA, setA = psu.getCurrent()

print("Measured voltage {} V (set {} V)".format(measV, setV))
print("Measured current {} A (set {} A)".format(measA, setA))

sleep(10)

psu.setChannelEnable(False)

# And in the end disconnect
psu.disconnect()

Example usages

There are of course many applications especially in physics experiments such as setting magnetic fields, controlling heating elements, measuring pressure using the power dissipated in a Pirani gauge, controlling laser power and frequency, etc.

Recording voltage-current curves

A simple application of this library is just recording constant current curves when characterizing electronic parts or systems. In this case one can simply scan the voltage until the output current reaches a desired limit and record the measured current at each point. In addition this can of course be repeated more than once to reduce measurement error on noisy systems but since the supply will only return with a resolution of 10 mA this won’t be necessary in many cases. A simple example script that does exactly that and plots the result with matplotlib is supplied in the examples directory of the pyka3005p repository.

A simple example measurement of a 1N4001 diode in forward direction up to 2A of current (exceeding the specification of 1A) is shown in the graph below:

A simple example on how to capture such data is available as GitHub GIST

This article is tagged:

• Python
• Physics
• Hardware
• Measurements
• Basics
• Programming