New UPB binding for OH2

I’m developing a binding for UPB (Universal Powerline Bus). It is available for early testing from my branch on GitHub.

If you have UPB devices and are comfortable building from source, please give it a spin. This is very early code so there are probably some rough edges!

There is a previous openHab 1.x UPB binding, but I had trouble getting that to work with OH2. Aside from some small pieces carried over from the old binding, this is a rewrite using OH2 concepts.

FYI there was an old pull request that has been closed

Oh, I had missed that one. I think mine might have a few more features but I’ll take a look at it and see if something can be reconciled.

@cvanorman fyi

The bindings should be pretty similar functionally. The main difference is that mine does not treat links (scenes) as Things. I think this is more natural but is a matter of taste I guess.

The other point is that I reworked the serial I/O handling and I believe it corrects some concurrency issues in the 1.x binding (and still present in the other PR).

I’m still running OpenHAB 1.x for my production server at my house, in part because I have ~15 UPB devices with an RS232 serial PIM controller overseeing them.

I encourage your efforts to build a stable UPB binding that works well with OpenHAB2.

If you need beta-testers I may be able to find time to set up a test OpenHAB2 installation to try out against my house’s installed UPB components.

That would be helpful! The latest code is in the PR.

I didn’t realize OH2 had been made so easy to use with Mac OS X. I was able to get a basic OH2 install up & running on my main Mac in an hour or so, no need to dedicate separate hardware & deal with keyboards, displays, etc.

Can you briefly detail the config changes you needed to make in order to:
a) Get your OH2 installation to listen to a USB --> RS232 serial converter
b) Install & configure the basic UPB binding
c) set up a basic Thing for a physical UPB device

I am very familiar with OH1.x so I don’t need a detailed hand-holding, but it’d be helpful if you could point me to the proper config file names / locations & give me a few sample entries to work from.

Hopefully from there it should be a short hour or so to just plug in my spare RS232 PIM module & then be able to do live testing across the ~15 different UPB devices I have in my house.

For the binding, you can find a link to the JAR file in the PR. Drop that in your addons folder (the location would be installation-specific).

There is a sample config snippet in the README, that should cover the things config.

The items are configured just like any other lights/dimmer items, so the openHAB user guide applies. You can also use Paper UI to configure the items, that might be easier.

1 Like

I was able to get the binding installed & working on a brand new OH 2.5.1 stand-alone install on my Mac. Currently I have just one UPB device (a Simply Automated™ model US2-40 dimmer wall switch) configured and it’s working fine.

In the coming week or two I will set up a series of test rules to send both periodic and random UPB commands to all the ~15 UPB devices at my house. I have DEBUG-level logging turned on for the UPB binding which’ll help verify proper operation.

A big thank-you for your efforts on this binding so far. I have around USD $2,500 invested in permanently-installed UPB devices (not to mention another 20+ hours spent re-wiring them, and another 100+ hours coding OpenHAB rules for them.) A working OH2-compatible UPB binding is absolutely required for me to be able to even consider migrating my live OH setup from 1.8 to 2.x.

If you’re interested I’m happy to help out with documentation and/or specific requests related to testing & debugging.

On a Mac it takes a bit of work to get a usable /dev/tty.usbserial which OpenHAB can address. Once this is done (see details below) it is then relatively straightforward to continue configuring the UPB binding normally.

OpenHAB notes:
:point_right: I did not have to add any command-line options to the openhab startup script in order to allow OpenHAB to access the /dev/tty.usbserial device. It simply “just works” as-is.

:point_right: I did not use the PaperUI or any other GUI front-ends to install or configure the UPB binding. I just moved the org.openhab.binding.upb-2.5.1-SNAPSHOT.jar into the ~/openhab-2.5.1/addons/ directory and reloaded OpenHAB. I then updated my Things, Items, and Sitemap as follows:


My `default.things` configuration:
Bridge upb:serial-pim:pim "UPB PIM" @ "Bedroom Test" [port="/dev/tty.usbserial" ] {
  Thing generic backbed_ceiling_light  "Back Bedroom Ceiling Light" [networkId=22, unitId=8] {
      Type switch : power
      Type dimmer : level


My `default.items` configuration:

Dimmer BackBed_Ceiling_Light { channel="upb:generic:pim:backbed_ceiling_light:level" }


My `default.sitemap` configuration:
sitemap default label="My home automation" 
    Frame label="Back Bedroom" {  
           Slider item=BackBed_Ceiling_Light label="Back Bedroom Ceiling Light"

events.log output

Events Log
2020-02-16 16:33:47.699 [ome.event.ItemCommandEvent] - Item 'BackBed_Ceiling_Light' received command 57
2020-02-16 16:33:47.713 [nt.ItemStatePredictedEvent] - BackBed_Ceiling_Light predicted to become 57
2020-02-16 16:33:47.723 [vent.ItemStateChangedEvent] - BackBed_Ceiling_Light changed from NULL to 57

openhab.log output (DEBUG on)

Openhab Log
2020-02-16 16:22:10.404 [DEBUG] [nding.upb.internal.UPBHandlerFactory] - Creating thing upb:serial-pim:pim
2020-02-16 16:22:10.410 [DEBUG] [binding.upb.handler.SerialPIMHandler] - Initializing Serial UPB PIM upb:serial-pim:pim.
2020-02-16 16:22:10.411 [DEBUG] [enhab.binding.upb.handler.PIMHandler] - Initializing UPB PIM upb:serial-pim:pim.
2020-02-16 16:22:10.414 [DEBUG] [nding.upb.internal.UPBHandlerFactory] - Creating thing upb:generic:pim:backbed_ceiling_light
2020-02-16 16:22:10.419 [DEBUG] [.binding.upb.handler.UPBThingHandler] - initializing UPB thing handler upb:generic:pim:backbed_ceiling_light
2020-02-16 16:22:10.420 [DEBUG] [.binding.upb.handler.UPBThingHandler] - DEV 8: Controller status is OFFLINE
2020-02-16 16:22:10.421 [DEBUG] [enhab.binding.upb.handler.PIMHandler] - child handler initialized: upb:generic:pim:backbed_ceiling_light
2020-02-16 16:22:10.421 [WARN ] [.binding.upb.handler.UPBThingHandler] - DEV 8: received cmd REFRESH but no bridge handler
2020-02-16 16:22:10.915 [INFO ] [binding.upb.handler.SerialPIMHandler] - opening serial port /dev/tty.usbserial
2020-02-16 16:22:10.943 [INFO ] [binding.upb.handler.SerialPIMHandler] - Serial port is initialized
2020-02-16 16:22:10.944 [DEBUG] [binding.upb.handler.SerialPIMHandler] - Starting receive thread
2020-02-16 16:22:10.946 [DEBUG] [.binding.upb.handler.UPBThingHandler] - DEV 8: Controller status is ONLINE
2020-02-16 16:22:10.946 [DEBUG] [.binding.upb.handler.UPBThingHandler] - DEV 8: Controller is ONLINE. Starting device initialisation.
2020-02-16 16:22:10.949 [DEBUG] [b.binding.upb.handler.SerialIoThread] - Writing bytes: 07506108FF0041
2020-02-16 16:22:10.963 [DEBUG] [b.binding.upb.handler.SerialIoThread] - UPB Message: PE
2020-02-16 16:22:10.964 [WARN ] [b.binding.upb.handler.SerialIoThread] - received ERROR response from PIM
2020-02-16 16:22:10.997 [DEBUG] [b.binding.upb.handler.SerialIoThread] - UPB Message: PA
2020-02-16 16:22:11.296 [DEBUG] [b.binding.upb.handler.SerialIoThread] - UPB Message: PK
2020-02-16 16:22:11.297 [DEBUG] [b.binding.upb.handler.SerialIoThread] - ACK received
2020-02-16 16:32:01.558 [DEBUG] [b.binding.upb.handler.SerialIoThread] - UPB Message: PU08046100088632D2
2020-02-16 16:32:01.565 [DEBUG] [b.binding.upb.internal.UPBController] - received message, network=22 src=8 dst=0 cmd=DEVICE_STATE
2020-02-16 16:32:01.872 [DEBUG] [b.binding.upb.handler.SerialIoThread] - UPB Message: PU08056100088632D2
2020-02-16 16:32:01.874 [DEBUG] [b.binding.upb.internal.UPBController] - received message, network=22 src=8 dst=0 cmd=DEVICE_STATE
2020-02-16 16:32:03.274 [DEBUG] [b.binding.upb.handler.SerialIoThread] - UPB Message: PU0804610008860005
2020-02-16 16:32:03.274 [DEBUG] [b.binding.upb.internal.UPBController] - received message, network=22 src=8 dst=0 cmd=DEVICE_STATE
2020-02-16 16:32:03.590 [DEBUG] [b.binding.upb.handler.SerialIoThread] - UPB Message: PU0805610008860004
2020-02-16 16:32:03.591 [DEBUG] [b.binding.upb.internal.UPBController] - received message, network=22 src=8 dst=0 cmd=DEVICE_STATE
2020-02-16 16:33:47.717 [DEBUG] [b.binding.upb.handler.SerialIoThread] - Writing bytes: 08106108FF223925
2020-02-16 16:33:47.762 [DEBUG] [b.binding.upb.handler.SerialIoThread] - UPB Message: PA
2020-02-16 16:33:48.095 [DEBUG] [b.binding.upb.handler.SerialIoThread] - UPB Message: PK
2020-02-16 16:33:48.095 [DEBUG] [b.binding.upb.handler.SerialIoThread] - ACK received

Full notes on Mac OS X install and USB/RS232 adapter setup

Notes on getting a USB-serial adapter working with OpenHAB 2.5.1 under Mac OS X 10.14.6:

OS System version: Mojave / OS X 10.14.6 running on a MacBook Pro 2019, 15" (MacBookPro15,1)
Kernel: Darwin Kernel Version 18.7.0: Thu Jan 23 06:52:12 PST 2020

Java version: (from java -version at the command line):

java version "11.0.2" 2019-01-15 LTS
Java(TM) SE Runtime Environment 18.9 (build 11.0.2+9-LTS)
Java HotSpot(TM) 64-Bit Server VM 18.9 (build 11.0.2+9-LTS, mixed mode)
Note on my Java version & OpenHAB 2.5.1

Upon starting OpenHAB runtime from the command line on my machine, I get the following output & errors:

MBP2019:openhab-2.5.1$ ./
Launching the openHAB runtime...
Unable to find any JVMs matching version "1.8".
org.ops4j.pax.url.wrap [org.ops4j.pax.url.commons.handler.HandlerActivator] DEBUG : Handler for protocols [wrap] started

Despite this error, for whatever reason OpenHAB installed & is running fine. I am a bit confused as to why this is but included it here as it is note-worthy.

OpenHAB version: OpenHAB 2.5.1 Stable Runtime
(downloaded from: )

OpenHAB UPB Binding:
The upb-2.5.1.jar linked in this pull request.


My building’s UPB device installation
Details about my personal UPB hardware config in this forum post.

USB-C to USB-A adapter
MacAlly™ USB-C to USB-A Hub with Ethernet Adapter, model UCHUB3GB

MacAlly adapter details

Screen Shot 2020-02-16 at 2.27.26 PM

USB-to-Serial converter hardware:
Plugable™ USB TO RS-232 DB9 SERIAL ADAPTER, model PL2303-DB9

Plugable™ Serial Adapter Details & Mac OS X driver software

Product chipset: PROLIFIC PL2303HX
Driver software (required to allow OpenHAB to talk to this device): * PL2303 Prolific MacOS/OS X 10.9, 10.10, 10.11, 10.12, 10.13, 10.14, 10.15 – Driver v2.0.0

Screen Shot 2020-02-16 at 2.20.42 PM

Notes: This Plugable™-brand USB-RS232 adapter is plug-and-play for some applications under both Windows 10 Pro and OS X 10.14. But in order to get a usable /dev/tty.usbserial entry to show up in Mac OS X 10.14 I had to install Plugable’s driver software. I had no problems doing this. I just downloaded the latest Mac OS X driver from Plugable’s drivers page, double-clicked the installer package, and started the install.

( If you have a no-name USB-RS232 adapter and can’t seem to find drivers for it you might want to try the power-user Mac serial drivers available at )

:point_right: :exclamation: OS X 10.13 and later versions: AFTER starting the Plugable™ driver software installation you must go to OS X System Preferences --> Security & Privacy --> General and click “Allow” to permit the installation & activation of the driver to continue and finish successfully. See also: Apple Technical Note TN2459, User-Approved Kernel Extension Loading.

Immediately after completing the install (and unplugging/replugging the USB-RS232 adapter), a /dev/tty.usbserial device became visible in /dev.

UPB Pulse Interface Module (PIM) hardware:
Simply Automated™ RS232 Computer Interface Module, model UMC-DB9-W

With the UPB RS232 PIM attached to the USB-RS232 adapter I then verified basic connectivity using the screen command-line utility:

hostname% screen /dev/tty.usbserial 4800
(4800 is the baud rate: UPB PIM only operates at 4800 baud.)

On a UPB PIM which has been factory reset to defaults, normal behavior is for it to monitor the powerline for UPB signals and to echo all received broadcasts through its RS232 port. If the USB-serial adapter is working properly, upon activating a UPB device (like pushing a physical UPB wall dimmer switch) there should be some corresponding code appearing in the screen session on your Mac:

Screen Shot 2020-02-16 at 3.21.17 PM

(Note, screen can be a bit tricky for newbies. To kill a screen session, press ctrl-a, then press k to kill the session, and then hit y to confirm.)

If you’re having problems with screen you could also use one of many stand-alone Mac OS X serial-terminal apps such as

Whatever method you use to verify serial-port connectivity be sure to completely quit out of the test program so that it releases the serial port. Otherwise OpenHAB won’t be able to access the serial port & will return a “serial port in use” error in the logs.

If you open a terminal program but can get no response from the UPB RS232 PIM module it may be in “PULSE” mode. Resetting it to factory defaults (paper-clip reset) will put it back in “MESSAGE” mode which should give clear text to your serial terminal program.

:point_right: Special note for GUI serial apps:


Most Mac OS X serial-terminal apps attempt to grab direct control of serial ports at the lowest possible level. With a separate serial driver installed, some apps complain that they cannot take control of the serial port device. If your GUI serial app gives you an option to attempt to work with a driver anyway I suggest you allow it. (Click “Proceed” in this example, taken from version 1.4.2.):

Screen Shot 2020-02-16 at 3.28.21 PM

Thanks for testing, good to know that it works.

Did this updated OH2-native UPB binding ever get committed to the official OH2 bindings?

The PR is still open, so not yet. It had a few rounds of feedback and updates. I still intend to address the feedback and get it merged, but haven’t had much time the past few months.

Good news, the UPB binding has been released in openHAB 2.5.9!