{"id":22220919,"url":"https://github.com/nokia/rcm-bluez","last_synced_at":"2025-07-27T16:30:48.419Z","repository":{"id":35737830,"uuid":"153593855","full_name":"nokia/rcm-bluez","owner":"nokia","description":"Remote Connection Manager (RCM) for Bluetooth ","archived":false,"fork":false,"pushed_at":"2022-04-12T23:11:44.000Z","size":16613,"stargazers_count":8,"open_issues_count":6,"forks_count":5,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-04-14T13:07:16.087Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nokia.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-10-18T08:56:22.000Z","updated_at":"2024-04-14T13:07:16.088Z","dependencies_parsed_at":"2022-08-08T11:00:20.356Z","dependency_job_id":null,"html_url":"https://github.com/nokia/rcm-bluez","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nokia%2Frcm-bluez","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nokia%2Frcm-bluez/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nokia%2Frcm-bluez/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nokia%2Frcm-bluez/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nokia","download_url":"https://codeload.github.com/nokia/rcm-bluez/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227817163,"owners_count":17824199,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-02T23:10:58.100Z","updated_at":"2024-12-02T23:10:58.728Z","avatar_url":"https://github.com/nokia.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Remote Connection Manager (RCM)\n\nRemote Connection Manager (RCM) - is a research prototype of the \n[\"Application-agnostic remote access for Bluetooth Low Energy\"](https://ieeexplore.ieee.org/document/8406942/).\n\n##### RCM is:\n- An abstract layer on top of BLE Protocol Stack\n- Provides a transparent connectivity to remote BLE devices\n\tConnectivity is said transparent when the native applications can access both local\n\tand remote short-range devices without any modification\n\n- Has no impact on the Bluetooth applications nor the Bluetooth peripherals\n- Easy to deploy: RCM is purely software and can be installed as an update of the Bluetooth Protocol Stack\n- Offering real-time communication between clients and remote peripherals as if they were in proximity\n- Doesn’t rely on complex infrastructures, dedicated hardware nor advanced network features\n- Implemented under Bluez 5.43 and tested on real devices.\n \nRCM is a proxy-based solution. Thus, we define two kinds of centrals:\n- A client is a central device that runs applications accessing the services offered by a peripheral.\nThe client role is usually played by powerful devices such as smartphones,\nPC, tablets, etc. The client may have Bluetooth capabilities but only requires a BPS for our mechanism. The\nclient device is supposed to be connected to an IP network (e.g. Internet).\n\n- A proxy is a central device reachable via an IP network and having Bluetooth capabilities.\nIt may also filter an incoming connection that does not comply with configured privacy rules.\nSimilarly to central devices, it may be a smartphone, tablet, laptop, etc.\nIt supposed to be connected to an IP network reachable from the client and located in close proximity to some Bluetooth peripherals.\n\nIn the current version of RCM, client and proxy are implemented separately, but it may change lately.\nPlease note that this implementation is still in its initial state and is currently in progress.\n\n# Content\n\nThe repository contains client, proxy, visualizer, app and screenshots folders.\n1. The first two of them are the rcm-client and rcm-proxy respectively with the bluez-5.43 sources.\nRCM itself is implemented as a plugin.\n\n2. Visualizer provides GTK graphic interfaces for client and proxy side.\nThe client vis is basically a window to enter the proxy's IP and port number and launch the connection.\nIt doesn't do anything else.\nThe proxy side is a bit more complex and represents the topology, logs and a way to configure your proxy.\nEverything is tested on debian and ubuntu. Graphic interface is based on css but its representation may differ depending on the installed gui...\n\n3. app folder provides the WebBluetooth applications for the devices we used for testing.\nUsually, BLE applications are related to a particular BLE device offering specific UUIDs.\nNormally this applications are provided for Android OS, IOS, Windows OS ... \nWe only used Linux for the moment, so WebBluetooth was a very interesting to us.\nOne of the provided applications is [this open-source one](https://github.com/urish/web-lightbulb).\nThe second one is the same but adjusted for the second device we possess.\nTo write your own WebBluetooth app in most of cases you may need to reverse engineer your device...\nYou can read more about it [here](https://medium.com/@urish/start-building-with-web-bluetooth-and-progressive-web-apps-6534835959a6).\n\nNormally, you should be able to use any BLE application.\nWebBluetooth is just a framework allowing you to use web pages to communicate to your BLE devices through bluez.\nIt is available on chromium and google chrom web browsers by activating the following experimental flag:\n`chrome://flags/#enable-experimental-web-platform-features`\n\nYou may also use `hcitool` or `gatttool` to communicate to your device from the command line.\n\n4. The screenshots of \"how it should be\" as weel as the explanation of different fields in proxy visualizer are provided in the Screenshots folder.\n\n# Needed packages\n\nThe provided code includes the sources of *bluez-5.43*, so you do not need to download them separately. \nThe provided sources contain some of our callbacks needed by RCM, so please use our modified version of bluez.\n\nYou can check how to install bluez from sources [here](https://www.jaredwolff.com/get-started-with-bluetooth-low-energy/#hide1)\n\nBriefly, you will need the following packages:\n\n`libglib2.0-dev\nlibdbus-1-dev\nlibusb-dev\nlibudev-dev\nlibical-dev\nsystemd libreadline-dev`\n\nMay be also `automake gcc libtool gdb` etc. if not already installed\n\nFor the visualizers:\n\n`libglib2.0-dev\nlibdbus-glib-1-dev\nlibgtk-3-dev`\n\nYou can use the provided script compile_rcm.sh that combines general steps for successful compilation and installation.\nSee inside this script for more details.\nIf it crashes on the configure step, it will usually indicate you what package is missing.\nSo, just look carefully on the line where the configure script has crashed, install the missing package and run the script again.\n\nTo compile the visualizers, just go to a corresponding folder et run make it will create an executable.\n\n# How to run?\n\n1. Install the client and proxy parts on the corresponding Linux machines.\n\t\n`./compile_rcm.sh`\n\n`./run_bluez_rcm.sh`\n\n2. Check with hciconfig that your bluetooth interface is up:\n\n`hciconfig`\n\nIf it is marked as down, for example, like this:\n\n![hciconfig output](https://raw.githubusercontent.com/nokia/rcm-bluez/master/screenshots/hciconfig.png)\n\nYou may use the following command to activate the corresponding hci (hci0 in my case):\n\n`sudo hciconfig hci0 up`\n\nNote that you do not need a physical bluetooth interface on client side because the communication will pass through the proxy.\nSo, you can use the emulator provided by bluez and located in the emulator folder. See *\"How to create a virtual hci\"* section below.\n\n3. Run the bluetooth daemon with the coresponding rcm plugin. Check the run_bluez_rcm.sh script to know how to run it with gdb.\n\n# How to create a virtual hci?\n\n1. First, you need insert the special kernel module by running the following command:\n\n`sudo modprobe hci_vhci`\n\n2. Then, open your script_compile inside the client/bluez-5.43 and add the key --enable-experimental right after the ./configure word, keep everything that follows.\n\n`./configure --enable-experimental ...`\n\nFor example, your line will become like this:\n\n`./configure --enable-experimental --enable-library --enable-debug CFLAGS=\"-std=c99\" LIBS=\"-lgio-2.0 -lgobject-2.0\"`\n\n3. Compile everything as for the first time (decomment the first lines inside the compile_rcm.sh)\n\n4. Now, if you enter the emulator folder, you will see `btvirt` appeared.\n\nThis is our emulator. We could use it to create a virtual hci with BLE support :\n\n`sudo ./btvirt -l 1 -L`\n\nNow, if you execute `hciconfig`, you will see your virtual interface created, for example something like this should appear. Look at the Bus parameter, it's value is *Virtual*, so we are sure that this is our emulated device:\n\n![hciconfig output](https://raw.githubusercontent.com/nokia/rcm-bluez/master/screenshots/hciconfig.png)\n\nYou can put it up or down as a normal hci interface. You will also have a folder corresponding to this adapter appeared in `/var/lib/bluetooth`. As usual, the cache and discovered devices will be stored there.\n\n# What next?\n\n1. Once you are inside the proxy, it is not listening yet. First, it should be initialized.\nInitialize proxy means configuring the list of devices it can see (e.g. to limit the noise and do not discover the devices of your neighbours).\nTo do so, run the visualizer and click on Initialize button.\nA new window will appear and show the discovered devices.\nSelect the ones you want to keep discovering. By default, this filter is empty.\nLater, we plan to save it into a file and load when proxy runs. Bu it is not implemented yet.\n\nWhen Filter button is clicked, the proxy create its initial filter and starts listening on the port number 1500.\n\n2. Client side, you can run the vis and connect to your proxy IP, port 1500.\n3. In the proxy vis you will observe your client appearing.\n4. By default, clients are not configured and are now allowed to discover any device.\nSo, you need to configure the client filters.\nClick on the Configure Client button, select the client from the list (click twice on a corresponding line).\nThen drag and drop the devices from the proxy init filter (left part) to the client filter (right part) and click on Validate button.\n5. Now you can run an application on the client side and try to discover, connect and write a characteristic value.\nFor the moment, only write is possible.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnokia%2Frcm-bluez","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnokia%2Frcm-bluez","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnokia%2Frcm-bluez/lists"}