# piBeacon - DIY Beacon with a Raspberry Pi ## Overview ![](https://cdn-learn.adafruit.com/assets/assets/000/012/685/medium800/raspberry_pi_adafruit_pibeacon_logo_final.bmp?1386179745) This learning guide will show you how you can take your Raspberry Pi (or almost any Linux-based device with a bit of poking and prodding) and turn it into an Beacon node using our [Bluetooth 4.0 USB Module](http://www.adafruit.com/products/1327) and the open source Bluez stack. ![](https://cdn-learn.adafruit.com/assets/assets/000/012/606/medium800/raspberry_pi_1327_LRG.jpg?1386024289) # What You'll Need - [A Raspberry Pi](http://www.adafruit.com/products/998 "Link: http://www.adafruit.com/products/998") (any model should be OK) - [A Bluetooth 4.0 USB Module](http://www.adafruit.com/products/1327 "Link: http://www.adafruit.com/products/1327") (not every module works with Bluez, though ours definitely does!) - A iOS 7.0 based device (recent iPhone/iPad/iPod Touch) to test with - An iBeacon reader app from the App Store to test with (Try [Locate Beacon](https://itunes.apple.com/us/app/locate-beacon/id738709014?mt=8), but any free iBeacon watcher ought to be OK!) # Acknowledgement A big thanks to Tony Smith at The Register for putting together his [tutorial](http://www.theregister.co.uk/2013/11/29/feature_diy_apple_ibeacons/) on configuring Bluez to transmit Beacon data! # piBeacon - DIY Beacon with a Raspberry Pi ## What is a 'Beacon'? 'Beacons' are based on Bluetooth Low Energy (part of the new Bluetooth 4.0 standard), and at it's heart is a way to advertise location specific data one-way, or provide basic indoor navigation via individual Beacon nodes. The way it works is actually very simple. Any BLE device typically advertises a certain amount of data to let other devices (like your phone) know that they exist and they're available. The advertising packet that these devices send out might include information like key services offered by the device, a human-readable short devices name, etc. Beacons take this short advertising frame, and appends a custom payload in the "Manufacturer Specific Data" field which includes a unique 128-bit UUID to identify companies or unique entities, as well as two 16-bit values ('Major' and 'Minor', or whatever you'd like to call them) that allow you to differentiate specific stores/premises (Major) and individual Beacon nodes (Minor). That's basically it. All the rest of the magic is on the app side where your phone listens for these advertising frames, and when it detect something it estimates the distance to the node and displays some sort of alert. It's terribly simple, but that's probably what makes it so interesting and also so inexpensive to implement! # Why use a Beacon? Beacons can be used to determine somebody's proximity to locations of interest. For instance, in museums they can be used to trigger an audio recording at a particular exhibit or in retail can be used to send promotions and alerts to customers' smartphones when they are near or inside a store. In large buildings like airports or museums, beacons help guide visitors to their destinations by providing location-specific information directly to their devices. In warehouses or hospitals, beacons are attached to equipment or tools to monitor their location and usage. They can provide attendees with schedules, session information, or promotional material as they move around different areas in a conference. Beacons can also trigger smart home actions, like turning on lights or adjusting the thermostat when someone enters a room. # How Does it Work in Pratice? Essentially, all you need to do is insert a specific set of bytes into the optional **[Manufacturer Specific Data](https://www.bluetooth.org/en-us/specification/assigned-numbers/generic-access-profile)** field of the advertising packet on your Bluetooth Low Energy device. Inside this field, you need the following values: - **ID** (uint8\_t) - This will always be 0x02 - **Data Length** (uint8\_t) - The number of bytes in the rest of the payload = 0x15 (21 in dec) - **128-bit UUID** (uint8\_t[16]) - The 128-bit ID indentifying your company/store/etc - **Major** (uint16\_t) - The major value (to differentiate individual stores, etc.) - **Minor** (uint16\_t) - The minor value (to differentiate nodes withing one location, etc.) - **TX Power** (uint8\_t) - This value is used to try to estimate distance based on the RSSI value For example, the following is a valid iBeacon payload (separators added for clarity sake): ``` 02 | 15 | E2 0A 39 F4 73 F5 4B C4 A1 2F 17 D1 AD 07 A9 61 | 00 00 | 00 00 | C8 ``` The only other missing piece is that, following the Bluetooth standard, the Manufacturer Specific Data needs to be preceded by the [Company Identifier](https://www.bluetooth.org/en-us/specification/assigned-numbers/company-identifiers). The company identifier for Apple, for example, is **0x004C** , which we'll use for the example above. # piBeacon - DIY Beacon with a Raspberry Pi ## Compiling Bluez In order to use your Raspberry Pi to send out Beacon data in the advertising frame, we'll need to install a few open source tools, mainly **Bluez** # Check if you already have Bluez **If you already have a modern version of Bluez you do not need to compile and can skip to step 4!** On your Raspberry Pi, try running `sudo apt-get install bluez` and then `dpkg --status bluez | grep '^Version:'` If you get something like **Version: 5.23-2+rpi2** Where the version is greater than 5.11 you can skip the installation and compilation steps. # 1. Install Required Libraries ``` sudo apt-get install libusb-dev libdbus-1-dev libglib2.0-dev libudev-dev sudo apt-get install libical-dev sudo apt-get install libreadline-dev ``` Danger: ![](https://cdn-learn.adafruit.com/assets/assets/000/012/607/medium800/raspberry_pi_1_AptGet.png?1386025545) # 2. Download Bluez ``` sudo mkdir bluez cd bluez sudo wget www.kernel.org/pub/linux/bluetooth/bluez-5.11.tar.xz ``` ![](https://cdn-learn.adafruit.com/assets/assets/000/012/608/medium800/raspberry_pi_2_wget_bluez.png?1386025691) # 3. Unzip and Compile Bluez Next you need to actually build Bluez on the Pi. This step may take a while, but should work without any hiccups if you properly installed all the libraries in step one above: ``` sudo unxz bluez-5.11.tar.xz sudo tar xvf bluez-5.11.tar cd bluez-5.11 sudo ./configure --disable-systemd sudo make sudo make install ``` ![](https://cdn-learn.adafruit.com/assets/assets/000/012/609/medium800/raspberry_pi_4_make_done.png?1386025893) # 4. Insert the USB Module and Reset Once Bluez has been built, shut down your computer with **sudo shutdown -h now** and once its Halted, **insert your [Bluetooth 4.0 USB Module](http://www.adafruit.com/products/1327 "Link: http://www.adafruit.com/products/1327") and then restart the Raspberry Pi** so that all of the changes we have made can take effect. # piBeacon - DIY Beacon with a Raspberry Pi ## Adding Beacon Data In the ' **bluez-5.11**' folder that we previously created, we can start entering the mandatory Beacon data and advertising it using **hcitool** , which we built when compiling Bluez. # 1. Check for your USB Module This should give you a list of devices on your system: `tools/hciconfig` (if you compiled bluez) or `hciconfig` (if you apt-get'd bluez) If everything is properly configure you will see your Bluetooth 4.0 USB Module like this: ![](https://cdn-learn.adafruit.com/assets/assets/000/012/610/medium800/raspberry_pi_5_reset_then_hciconfig_cropped.png?1386026256) On a Raspberry Pi 3 you'll see the Bus is UART, not USB! ![](https://cdn-learn.adafruit.com/assets/assets/000/035/717/medium800/raspberry_pi_hciconf.png?1473832587) # 2. Enable the USB Device Next you can enable the device with the following commands, turning off device scanning since this can cause problems when advertising. If you're using the compiled bluez, add `tools/` before each call to `hciconfig` ```terminal sudo hciconfig hci0 up sudo hciconfig hci0 leadv 3 sudo hciconfig hci0 noscan ``` Then run the hciconfig tool again and you should see that the device is marked as **UP** and **RUNNING** : ```terminal hciconfig ``` ![](https://cdn-learn.adafruit.com/assets/assets/000/012/611/medium800/raspberry_pi_6_starthci_then_setibeacon_cropped.png?1386026565) # 3. Enter the Beacon Advertising Data The last thing to do is to enter the Beacon advertising data, which we can do with the following command (which should all be on one line): ```terminal sudo hcitool -i hci0 cmd 0x08 0x0008 1E 02 01 1A 1A FF 4C 00 02 15 E2 0A 39 F4 73 F5 4B C4 A1 2F 17 D1 AD 07 A9 61 00 00 00 00 C8 00 ``` **FF** identifies the start of the Manufacturer Specific Data, **4C 00** is Apple's company ID (0x004C), and then you can see the rest of the Beacon payload until **C8**. # Results on a Bluetooth Debugger Just to show that this actually works, you can see the results using a Bluetooth Low Energy sniffer below: ![](https://cdn-learn.adafruit.com/assets/assets/000/012/612/medium800/raspberry_pi_NordicCaptureCropped.png?1386026861) And here is the raw advertising frame from a different sniffer: ![](https://cdn-learn.adafruit.com/assets/assets/000/012/614/medium800/raspberry_pi_SnifferRaw.png?1386027470) # piBeacon - DIY Beacon with a Raspberry Pi ## Testing it on iOS To test that this actually works you'll need an iOS 7 based iPad/iPhone/iPod Touch, and a Beacon application. Start the app up, going into 'Listen' mode, and you should see a screen similar to the capture below, where the range will go in and out depending on your proximity to the node: ![](https://cdn-learn.adafruit.com/assets/assets/000/012/613/medium800/raspberry_pi_screen568x568.jpeg?1386027040) Danger: ## Featured Products ### Xinghuatian Tech Bluetooth® 4.0 USB Module [Xinghuatian Tech Bluetooth® 4.0 USB Module](https://www.adafruit.com/product/1327) Add Bluetooth® capability to your computer super fast with a Xinghuatian Tech Bluetooth® 4.0 USB Module. This adapter is backwards compatible with v2.1 and earlier, but also supports the latest v4.0/ Bluetooth® Low Energy. Inside lies a In Stock [Buy Now](https://www.adafruit.com/product/1327) [Related Guides to the Product](https://learn.adafruit.com/products/1327/guides) ### Raspberry Pi Model B 512MB RAM [Raspberry Pi Model B 512MB RAM](https://www.adafruit.com/product/998) Adafruit ships the **Raspberry Pi Model B 512MB RAM** as of 10/18/2012. The Raspberry Pi® is a single-board computer developed in the UK by the Raspberry Pi Foundation with the intention of stimulating the teaching of basic computer science in schools. The Raspberry... No Longer Stocked [Buy Now](https://www.adafruit.com/product/998) [Related Guides to the Product](https://learn.adafruit.com/products/998/guides) ## Related Guides - [Adafruit 2.4" PiTFT HAT with Resistive Touchscreen Mini Kit](https://learn.adafruit.com/adafruit-2-4-pitft-hat-with-resistive-touchscreen-mini-kit.md) - [CircuitPython BLE Multi-Temperature Monitoring](https://learn.adafruit.com/circuitpython-multi-temperature-ble-monitoring.md) - [Glider Paper Airplane Controller](https://learn.adafruit.com/glider-paper-airplane-controller.md) - [Quickstart - Raspberry Pi RP2040 with BLE and CircuitPython](https://learn.adafruit.com/quickstart-raspberry-pi-rp2040-with-ble-and-circuitpython.md) - [MCP230xx GPIO Expander on the Raspberry Pi](https://learn.adafruit.com/mcp230xx-gpio-expander-on-the-raspberry-pi.md) - [Boomy Pi Airplay Boombox](https://learn.adafruit.com/boomy-pi-airplay.md) - [Bonjour (Zeroconf) Networking for Windows and Linux](https://learn.adafruit.com/bonjour-zeroconf-networking-for-windows-and-linux.md) - [Wireless Image Transfer with Circuit Playground Bluefruit and E-Ink Gizmo](https://learn.adafruit.com/wireless-image-transfer-with-circuit-playground-bluetooth-and-eink-gizmo.md) - [Pico Bluetooth Keyboard Bridge](https://learn.adafruit.com/pico-bluetooth-keyboard-bridge.md) - [Turning your Raspberry Pi Zero into a USB Gadget](https://learn.adafruit.com/turning-your-raspberry-pi-zero-into-a-usb-gadget.md) - [Raspberry Pi as an Ad Blocking Access Point](https://learn.adafruit.com/raspberry-pi-as-an-ad-blocking-access-point.md) - [How we designed an injection-molded case](https://learn.adafruit.com/how-we-designed-an-injection-molded-case-for-raspberry-pi.md) - [AtariFruit 2600 Joystick](https://learn.adafruit.com/atarifruit-2600-joystick.md) - [reef-pi Guide 6: pH Monitoring](https://learn.adafruit.com/reef-pi-guide-7-ph-monitoring.md) - [Read-Only Raspberry Pi](https://learn.adafruit.com/read-only-raspberry-pi.md)