Custom Bluetooth Controller is an app that allows your Android device to act as a client and establish a serial connection over bluetooth or bluetooth low energy to other bluetooth devices acting as servers. It focuses on making everything customizable because it is impossible to predict the needs of all its users, and so every option that is hard-coded and unchangeable will become a limitation to someone at some point.
When you first install the app it has an empty controller, so if you connect to a device, an empty screen will load up. You have to set up a controller first.
To set up a controller, click on the "Setup" button in the main screen.
The options button in the top right of the setup screen will have 3 options: "Add Control", "Save" and "Help". And once you start adding controls, a fourth option will appear: "Clear".
Add Control will open a dialog where you can choose what control to add.
Save will save all your changes in memory and close the setup screen.
Clear will erase all the controls from the screen but it won't delete them from memory until you save.
Help opens another screen where you can read a quick overview about each control.
When you add a control, you can drag and drop it anywhere on the screen or you can click on it to customize it.
Now let's look at each control in detail.
Button
When you first add a button you will have to choose whether it should be a square or a circle, and you can change its size later to make it rectangular or elliptical.
Buttons have two command types: "Press, Release" and "Continuous".
Press, Release will send a command the moment the button is pressed, and another command the moment it is released.
Continuous, when clicked, will start a loop that sends a command every specified interval, and the loop will stop when the button is pressed again. Note that the interval should be higher than the "Commands delay" in the app settings.
You can change visual aspects of the button: its size, color, position, text, text size, text color. And instead of setting a button text and color you can set an icon from a list of icons included with the app or from your device's storage.
Toggle
A toggles is very similar to a button except that it can be in two different states: on and off.
Its default state is the state it's in when the connect screen loads up.
Toggles have two command types: "On, Off" and "Continuous".
On, Off will send the on command when it's clicked and it's state changes to on, and will send the off command when it's clicked and it's state changes to off.
Continuous, when clicked and the state is set to on, will start a loop that sends a command every specified interval, and the loop will stop when it is pressed again and it's state changes to off. Note that the interval should be higher than the "Commands delay" in the app settings.
You can change visual aspects of the toggle just like you can with the button, but with a toggle you can set different texts or different icons for the two states.
Slider
A slider allows you to send a command from a large range of values.
You can choose to display a label that shows the current position of the button (value indicator), and the "Send on Release Only" option makes it so that a command is sent only when you release the button instead of continuously sending commands as you slide the button.
And because you can choose to have hundreads or thosands of commands, there is an auto-fill feature so you don't have to enter them manually.
Joystick
A joystick is sometimes more convenient than buttons for example if you want to control the movement of a robot/car/plane.
You can set different commands for different angles and power levels, and you can fill those commands automatically as well.
And the "Value Indicator" and "Send on Release Only" features are similar to the ones in sliders.
Color Picker
A color picker lets you choose a color from a palette and sends it as a hex value (example: 00E5FF) encoded as a string, and you can also choose to prepend a prefix or append a suffix to that value before it is sent. If you set the prefix to 0x then the hex value will be sent without encoding.
You can choose to add the alpha channel which will display a picker for opacity and include it in the color (example: C300E5FF)
And the "Color Indicator" is a small band under the color picker that will change it's color to let you know what the current selected color is.
"Send on Release Only" is just the same as in sliders and joysticks.
Gauge
The gauge is the latest control I've added, and it helps you monitor a changing value in a way that is more appealing than printing that value in the serial input.
Whenever you have one or more gauges in your controller, then every message that is received is checked to see if it starts with a gauge's prefix and ends with its suffix and if that's the case then that message will not be printed on the serial input (if it exists) and the number between the prefix and suffix will be used to update the gauge's value.
If the number ends with '%' then it's treated as a percentage. For example, a gauge's minimum value is 0, its maximum value is 200, its value prefix is "gpre" and its value suffix is "gsuf": if you receive a message "gpre50gsuf" then the gauge's value will change to 50 but if the message is "gpre50%gsuf" then the gauge's value will change to 100.
There are plenty of visual customizations for the gauge but they don't need explanation.
Serial In
This is where incoming messages will be displayed as long as they don't match a gauge command.
Serial Out
If you need to send special commands that are not binded to any other control, you can use Serial Out.
For any control, commands starting with 0x are treated as hex values and sent as bytes without encoding, while other commands are treated as strings and encoded using UTF-8.
Once you're done setting up your controller, click options and then Save.
Once you have a controller set up, click "Connect" from the main screen, which will open a dialog with a list of paired devices.
If you are using Android 5 (Lollipop) or less, the app will also start scaning for nearby devices, because starting with Android 6, Google doesn't allow apps to run bluetooth scans without requesting the location permission, and I chose not to request it.
So if the bluetooth module you want to connect to is not paired already, then for Android 6, 7 and 7.1: clicking the "New Device" button will open your device's bluetooth settings where you can pair with the bluetooth module and then coming back to find it in the paired devices list. But starting with Android 8, the app can request Android to perform a scan and let the user choose a device, the details of which will be given to the app, so clicking on "New Device" will open another dialog where you can choose a device to connect to.
Joystick
On the bottom left of joysticks there is a lock icon and clicking on it will unlock the central button and it will not rubber-band back to the center when you release it.
Serial In
On the bottom left of the Serial In control there is a lock icon and clicking on it will disable the auto-scrolling, and clicking on the icon on the bottom right will clear all the received messages.
You can access the app settings by clicking on the gear icon at the top right of the main screen.
Auto connect
If you only connect to one bluetooth module then there is no need to choose it everytime, you can just select it here and you will be connected to it automatically.
Auto reconnect
If you have auto reconnect enabled then the connect screen will never close on its own even if the connection is lost, but instead the app will keep trying to reconnect indefinitely until you press the back button to close the connect screen.
Commands delay
Some controls (slider, joystick, color picker and button's press and release) have the ability to send commands at a rapid rate making it difficult for the receiving module to discern between commands, so it's important to have a small delay between transmissions.
Serial timeout
This is similar to Arduino's Serial.setTimeout() function, when serial data starts coming in, the app will wait this amount of time for more data to come and combine all the data to form one message.
UUID settings
If you can connect to the bluetooth module and send and receive commands then you don't need to change this, but if your module uses a different service with a different UUID then you will need to input it here.
Save/Restore
In order to migrate your controller to a different device or to the same device after a factory reset or even if you want to use different controllers for different projects you can save your controller and restore it later.
The premium tier allows you to use the app without seeing any advertisements, and I'm always looking to add features that are exclusive to the premium users but do not limit the functionality for normal users.
The first of such features is multiple controllers. This allows you to have multiple controllers set up for different projects.
If you are a normal user you can mimick this feature by setting up a controller then saving it from the app settings, then setup another controller and save it as well and so on, and at the time of connection, you would restore the controller you need then connect.
This way normal users lose some convenience but they don't lose any functionality.
Here we will explore the changes and additions in v1.4
Android 12 support The app's codebase has been reviewed and changes have been made where needed to comply with Android 12 requirements.
App can now perform device discovery on Android 8 and higher When you click on "New Device" in the connect dialog, your device will start scanning for nearby devices and shows you a dialog from which you can choose a device to connect to. In the past, "New Device" used to launch your device's bluetooth settings where you can pair with the bluetooth device then you would come back to the app to find it in the paired devices list.
New control: gauge
Added slider and joystick value indicators
Added custom icons for buttons and toggles
Buttons and toggles can now be elliptical not just circular
Added continuous command type for toggles
Increased maximum slider levels to 65536 Previously, sliders had a maximum of 254 levels, however this was chosen arbitrarily and might not be sufficient for some users.
You can now set a prefix and suffix for color picker commands Previously, you could only set '#' as a prefix and no suffix could be set.
Commands starting with 0x are now treated as hex values and sent as is without encoding
Multiple controllers (premium only)
Added keep screen on, commands delay, serial timeout and custom bluetooth UUID settings
You can now save and restore to and from a file Previously, you could only copy the text and store it on your own and you would have to paste it in the app to restore.
Unlocking joystick now sends the power 0 command Previously, unlocking joysticks did not send any command.
Couldn't decrease slider commands to above 12 Fixed a bug where if you had a slider with a high number of levels you could only decrease the number of levels to 2-12 but not more.
Fixed control positioning for devices with right to left languages
About 100 other fixes and improvements
If you have any questions or suggestions don't hesitate to contact us: support@notroid.com