libble++: simple Bluetooth Low Energy on Linux.

Here’s the code on github!

I’ve been working on a Bluetooth Low Energy library for Linux. The emphasis is on modern C++ design, and simplicity of use. I started before BlueZ supported BLE in a meaningful manner, so this library uses bits and bobs from BlueZ, some linked from libbluetooth, and some extracted from the source code.

I don’t make use of any of the GATT (that’s the high level interface, which is implemented over the ATT protocol which itself is sent over bluetooth sockets) code within BlueZ, which is all implemented over DBus. I just construct the packets (that’s the code I pulled out of BlueZ) and send them over a bluetooth socket myself.

With the brief introduction out of the way, how about some code :).

Here’s a complete program which scans for BLE devices:

#include <blepp/lescan.h>

int main()
{
   BLEPP::log_level = BLEPP::LogLevels::Info;
   BLEPP::HCIScanner scanner;
   while (1) {
    std::vector<BLEPP::AdvertisingResponse> ads = scanner.get_advertisements();
   }
}

Is that about the shortest scanning example you’ve ever seen? 😎 I cheated very slightly by bumping up the log level. Otherwise it’d sit there scanning and generating no output whatsoever, which would not be all that much use.

I’ve also not commented this because I think it’s reasonably self evident. There are only two active lines, creating a scanner object and getting the scan results. I also bump up the logging level so it shows scan results without having to print stuff from the ads struct. Not that that is hard, but since more or less everything is optional information, it’s mildly tedious.

With that little hook out of the way, the library follows a socket-and-function design, much like XLib if you happen to know that. In other words, there’s a socket which all the functions use and which is created for you. If you have a simple interaction with BLE to write, you can just use the functions and never worry further. If you have a slightly more complex interaction, for example if you don’t want to block, then you can get the socket and select(), poll(), epoll() or use any other of your favourite system calls.

So as a result, there’s no framework. It’s just a library. It won’t steal your main loop or make it hard to integrate with any other I/O system you happen to have kicking around.

Interacting with a bluetooth device beyond scanning is a bit more complicated, because devices with interaction are a bit more complicated. It’s more or less the same model, except it uses callbacks (set via std::functions), because various bits of information can arrive asynchronously.

Here’s a complete example which shows how to connect to a temperature monitor and log the readings it gives. I’ve highlighted the non-trivial lines so you can see how much code and how much boilerplace there is (not much!):

#include <iostream>
#include <iomanip>
#include <blepp/blestatemachine.h>
#include <blepp/float.h>  //BLE uses the obscure IEEE11073 decimal exponent floating point values
#include <unistd.h>
#include <chrono>
using namespace std;
using namespace chrono;
using namespace BLEPP;

int main(int argc, char **argv)
{
	if(argc != 2)
	{	
		cerr << "Please supply address.\n";
		cerr << "Usage:\n";
		cerr << "prog <addres>";
		exit(1);
	}

	log_level = Error;

	//This class does all of the GATT interactions for you.
	//It's a callback based interface, so you need to provide 
	//callbacks to make it do anything useful. Don't worry: this is
	//a library, not a "framework", so it won't steal your main loop.
	//In other examples, I show you how to get and use the file descriptor, so 
	//you will only make calls into BLEGATTStateMachine when there's data
	//to process.
	BLEGATTStateMachine gatt;

	//This function will be called when a push notification arrives from the device.
	//Not much sanity/error checking here, just for clarity.
	//Basically, extract the float and log it along with the time.
	std::function<void(const PDUNotificationOrIndication&)> notify_cb = [&](const PDUNotificationOrIndication& n)
	{
		auto ms_since_epoch = duration_cast<milliseconds>(system_clock::now().time_since_epoch());
		float temp = bluetooth_float_to_IEEE754(n.value().first+1);

		cout << setprecision(15) << ms_since_epoch.count()/1000. << " " << setprecision(5) << temp << endl;
	};
	
	//This is called when a complete scan of the device is done, giving
	//all services and characteristics. This one simply searches for the 
	//standardised "temperature" characteristic (aggressively cheating and not
	//bothering to check if the service is correct) and sets up the device to 
	//send us notifications.
	//
	//This will simply sit there happily connected in blissful ignorance if there's
	//no temperature characteristic.
	std::function<void()> found_services_and_characteristics_cb = [&gatt, &notify_cb](){
		for(auto& service: gatt.primary_services)
			for(auto& characteristic: service.characteristics)
				if(characteristic.uuid == UUID("2a1c"))
				{
					characteristic.cb_notify_or_indicate = notify_cb;
					characteristic.set_notify_and_indicate(true, false);
				}
	};
	
	//This is the simplest way of using a bluetooth device. If you call this 
	//helper function, it will put everything in place to do a complete scan for
	//services and characteristics when you connect. If you want to save a small amount
	//of time on a connect and avoid the complete scan (you are allowed to cache this 
	//information in certain cases), then you can provide your own callbacks.
	gatt.setup_standard_scan(found_services_and_characteristics_cb);

	//I think this one is reasonably clear?
	gatt.cb_disconnected = [](BLEGATTStateMachine::Disconnect d)
	{
		cerr << "Disconnect for reason " << BLEGATTStateMachine::get_disconnect_string(d) << endl;
		exit(1);
	};
	
	//This is how to use the blocking interface. It is very simple. You provide the main 
	//loop and just hammer on the state machine struct. 
	gatt.connect_blocking(argv[1]);
	for(;;)
		gatt.read_and_process_next();

}

OK so there are come caveats.

Mostly, it’s not finished. I wrote the library to support the work I’m currently doing, and so I’ve not needed to do anything like everything that the BLE protocol supports. BLE also has a lot of features I doubt anyone’s seen in the wild. I don’t like implementing code I can’t use and test, so I’ve not got any interface to features I don’t currently use.

It’ll likely grow over time and get more features, but if there’s something you’d like in there, let me know. It might be easy for me to put in, or I can give pointers to help you write the necessary code.

Advertisements

Good job, TI, I half mean that

I was a little surprised today when trying to debug a board when one of the output voltages was 4.8 V. The main reason for the surprise is that the power supply is specced at 3.3V. And I didn’t make the supply, Texas Instruments did. In fact it’s one of these.

IMG_20160711_182949

Checking the manual reveals that TI do indeed claim that it’s supposed to output 3.3V. Time to find the regulator! There’s no continuity between USB power and the output so it’s not a short. Poking around on likely looking chips quickly reveals that the regulator is OUCH THAT SUCKER IS BOILING HOT! this one:

IMG_20160711_180224.jpg

And has the markings in very small “PHUI”. I got a far as googling “PHUI v” before it autocompleted to “PHUI voltage regulator”, so I guessed I was on the right track :). Not very further down the track the TI TPS730 datasheet crops up showing it’s a TPS73033, which is a 3.3V LDO regulator rated to 200mA. And did I mention it’s baking? It seems to be fried in a rather unfortunate mode (and just for good measure, the NR pin which ought to be at 1.22V is at 0.14). Also, it turns out that the entire circuit diagram was in the manual, so there was no need for that bit of minor sleuthing.

So why good job TI? Well, the other, much more important chips, such as the micro controller I’m programming are rated to 3.9V absolute maximum and it didn’t die with 4.8V across it. I’m pretty pleased about that, because I can imagine going round a cycle frying many chips before finding out the power supply was defective. :shudder: :(.

Well anyway, it’s fried and I can’t use it. I mean technically I’ve successfully programmed the chip and not fried anything as far as I know, but there’s another as yet untested chip on the board rated to only 4.8V absolute maximum. I can’t trust it, so I can’t use it and so as far as I care it’s broken.

And that means I’m free! This guy has a great philosophy which is that if something is broken then there’s no risk of breaking it so you may as well try to fix it. Fortunately, I have some old boards which I’m not currently using which have ST Microelectronics L78L33 SO-8 voltage regulators on them. They’re not LDO so getting 3.3V from 5V is a bit dubious and actually is not quite within spec, but whatever, both my chip and the one in the programmer (a CC2511) work all the way down to 2V, so I reckon that is won’t matter. Also, it’s only rated for 100mA, not 200mA like the original, but both the chips are low power wireless ones so I doubt the current will go too high even when it’s programming. And besides that won’t be for long.

Time to dead bug it! And pot it in hot melt!

IMG_20160711_182349IMG_20160711_182651

And it works! 😎

The LED perhaps to the surprise of no one is dimmer than before and the output voltage is 3.2V which is in fact well within spec for the 7833.