i’m currently working on an openHAB 2 binding for the Bose SoundTouch speakers. Bose’s SoundTouch System is comparable to the Sonos’ multi room system and has quite the same functionality.
I got some initial features working (volume/on,off/mute/presets/grouping) with my 10/20/30 speakers and I would share the code, but I have some ‘legal’ questions before making the code publicly available.
One question is: Is it a problem having brand and product names in the name space? Currently I named the binding ‘org.openhab.binding.bosesoundtouch’ - so i’m using the manufacturer’s name and the product name in my binding name, and also in the thing definitions and some other cases. Do I need to ask for permissions if I’m allowed to do this?
The other thing is: Currently the binding based on ‘reverse engineered’ knowledge of the protocol by tracing the communication between the app and the speakers. The protocol seems quite simple - simple XML messages pushed through a websocket connection.
Bose also provides an official API here: http://products.bose.com/api-developer/index.html - I studied the Terms and Conditions and for me (I’m not a lawyer) it seems to be quite fair. It would be great if someone with more background in legal things could review the terms if it’s okay to agree or if there would be legal issues related to the openHAB licenses. So is it better to life with the reverse engineered information or would it be okay (in perspective of openHAB) to agree to those terms and get the document?
Who has to agree to the terms and conditions, just me or has some ‘official openhab representative’ to agree to those terms and conditions? (also if we have to ask Bose if we are allowed to use their brand and product name to reference to their product - related to the first part of the question)
Or is it allowed to use the names in this context without asking for permission? How is it handled for other bindings?
I would be very interrested in your Bose communications information. I have a friend that wants to connect some Bose speakers in to a new implementation of openHab which I am currently installing him. Is there any possibility you would share this please? My email address is trevor.newsomeATgmail.com NOTE: Swap AT for correct symbol.
Hi Chris, I’m a new OpenHAB user who happens to work for Bose and be in the right place to get the answers for you, from Bose’s point of view.
On the trademark question, it’s fine to use the Bose and SoundTouch trademarks to accurately describe the binding and in the namespace as needed, we’d just ask that you not do it in a way that implies that it’s an official release or endorsed by Bose.
As for the API T&C, this sort of project is exactly what it’s meant for. If you agree to the terms for your own API access to develop the binding, that would be sufficient for you to distribute your code. If OpenHAB ultimately decides to include your code in an official release, someone representing the appropriate legal body should agree to the API T&C too (Eclipse or OpenHab Foundation? That’s a question for them)
Misha Hill
Intellectual Property Counsel, Bose Corporation
(note: this is not meant as legal advice, nor to create an attorney-client relationship)
Wow, great to seen an answer from the manufacturer directly, before I responded here - thanks @mishakim!
@marvkis, sorry that I didn’t comment before, somehow this topic escaped my attention…
IANAL either, but let me also provide some input:
Regarding the use of names within the code (and the name of the binding) it is good to have the confirmation from @mishakim that this isn’t an issue. I think these things are always clearly only a reference to 3rd party products and do not claim anybody’s endorsement. There hasn’t been any company ever expressing any concern about any of the existing bindings.
Regarding T&C: This is legally indeed often a bit tricky. Although the Bose T&Cs sound fair, I find sentences like
The Licensee agrees to use the API only to the extent of its documented and publicly disclosed capabilities
This directly means that you are forfeiting the possibility to do certain things through reverse engineering. And in practice, this can very easily happen: If you come across bugs that you can workaround by analyzing the protocol and doing calls that are not documented THAT way in the official docu, you are already breaking the agreement. This is not just theoretical - we had this for Sonos (where the developers also did reverse engineering and didn’t use any official API documentation).
Imho reverse engineering is legally ok as long as it does not involve any cryptography - then you would be in conflict with stuff like the DCMA etc. And as long as you are only publishing the code, but not using it in any commercial way yourself (i.e. selling licenses for it or using it in commercial products that you sell yourself), this is rather harmless.
So in general, my advice would be to go for the reverse engineering option as it leaves you more freedom. You are only using publicly available information (because the devices provide it to you in unencrypted form) and you are not bound to any T&Cs. @mishakim, please correct me if you feel that I have some distorted view here!
If OpenHAB ultimately decides to include your code in an official release, someone representing the appropriate legal body should agree to the API T&C too
@mishakim, Could you elaborate on why you think this is necessary? After all, openHAB is doing nothing different than distributing the work of @marvkis (without having any knowledge about the Bose API and its documents and thus not using it in any way).
Thanks Kai, I don’t disagree with your position on the legality of reverse engineering. The reason we offer the API is to save people the trouble, and so they can avoid having their integrations break if we update the product. That’s also the reason for the license terms against using undocumented capabilities, but we understand your concern, and are actually going to strike that language from the next rev of the license.
I’ll take back my comment about who needs to agree to the license for distribution purposes – the current agreement doesn’t really contemplate distribution, it was meant to allow for DIY tinkering. We’re working to address that, by adding something about what sorts of disclaimers or info should be included in distributed software based on our API. For now, it’s just anyone who wants access to the API documentation needs to agree to the license to get it. If you don’t need to see the documentation, you don’t need the agreement.
As for the use of the trademarks, we’re also working on providing some better guidance about what we prefer – the existing language text is a bit strong. The factual use of marks to accurately describe something is allowed by trademark law, at least in the US, we just want to avoid confusion about whether something is official or endorsed.
Thanks Misha, I fully understand your arguments and finding the right wording in legal matters is no simple task. Most companies chose the simple way and don’t provide APIs for independent developers at all. So I very much appreciate that Bose offers a public, documented and local API - that’s a great move!
i also investigated sindce December in the Soundtouch API from Bose. Beside the legal stuff, what is your current state of you implementation. I startet a first draft of a binding with Channls Player, Volume and for each Preset a channel. I also did a lot of test with POSTMAN against the API and controlled my Player.
sorry for the late answer - I was very busy with my usual work. But It’s really good to hear that there are people interested in my work.
Especially thanks to @mishakim to give a feeling about the manufacturer’s point of view on those things and @Kai for his valuable input.
I know the legal things can become very complicated. And there are also big differences in how things are handled between the US and Europe, especially when it comes to things like reverse engineering. Here in Europe (Yes, I live in Europe) reverse engineering is not as critical than it is in the US. And as I currently have no need for any documentation - I think I’ll continue how I started it. By just listening what’s spoken and try to learn the language by listening. @mishakim - We (me and my Family) really love the SoundTouch speakers. Bose did a great job here! I really don’t want to harm Bose in any way - We just want a better integration into our smart home and give this back to the OH community.
I just didn’t want to make an additional fork of OH2. I think as developer you should be able to add it to your OH2 repro, otherwise just ask.
The bad news is for OH1 users - the plugin currently relies on the new openHAB2 device discovery to find the SoundTouch speakers and therefore it currently won’t work with OH1. So, give openHAB2 a try. I have it running since last summer (for some homebrew devices) and last christmas I migrated everything from my OH1 instance into OH2 - and since then OH2 is my only instance running and controlling all my stuff
Okay, if you really want - take it and bring it to OH1
So far - this is the first shot and it’s not feature complete. And Okay, the code needs some refactoring and cleanup. But it works and especially things like grouping devices, changing volume or turning everything off when leaving and back on when coming home works for us. I’m really looking forward to hear from your experience with it
it depends how you start your openhab server. When you start it from the CLI by running the start.sh script just execute the line just before calling the start.sh script.
Hope this answer’s your question. If not please provide some more information about your openhab installation
now the binding is there but I only can add things manually… therfore I need to enter the config manual. I have everything but the port. Which port to enter?
Usually the Bose speakers should come up in your inbox / “Setup Wizard” when you start a search for the Bose speakers. Currently the binding uses a ‘mac’ like address provided from the device within the ‘Thing ID’ and it relies on that mac address during further communication. So therefore it currently won’t work if you add the devices manually.
Do you have anything from the ‘SoundTouchDiscoveryParticipant’ on the logs? Lines like:
2016-02-12 10:21:16.729 [WARN ] [SoundTouchDiscoveryParticipant] - SoundTouch Device Wohnzimmer delivered no MAC Address!
Even those ‘delivered no MAC Address!’ messages count. It seems not on every discovery message the MAC address is delivered and the good ones usually aren’t logged
well I don’t know how but now I have the items in!?
I checked the log and see a lot of messages like there: [dtouch.handler.BoseSoundTouchHandler] - Wrong Device-ID in Entity updates: Got: 689E194E9AE0 expected: 0a1689e4
To the messages you see: I assume you currently have some grouped speakers. Those messages are currently a cosmetic issue - Initially i assumed that the device-id the device reports is always the device-id from the reporting device. But in the meantime I found out that when we have a group of speakers, all slave speakers report the common state referring with the master speakers ID. But it’s not an issue, just ignore this message.
You can now proceed with adding your item’s to the config files. You can gather the thing id’s from the Paper UI’s configuration / thing page.
Okay, interesting. May I ask which model it is? And maybe the generation. I have a few 10’s, one 20 and one 30 and all the 3rd gen…
I’ll investigate on the message when I find some time…
