https://github.com/bertrandmartel/fadecandy-android
:sparkles: Fadecandy server library to manage your Fadecandy USB controlled LED driver on Android
https://github.com/bertrandmartel/fadecandy-android
android-library android-service fadecandy fadecandy-server led-controlling
Last synced: about 1 year ago
JSON representation
:sparkles: Fadecandy server library to manage your Fadecandy USB controlled LED driver on Android
- Host: GitHub
- URL: https://github.com/bertrandmartel/fadecandy-android
- Owner: bertrandmartel
- License: mit
- Created: 2016-09-04T00:56:41.000Z (almost 10 years ago)
- Default Branch: master
- Last Pushed: 2020-02-11T11:41:45.000Z (over 6 years ago)
- Last Synced: 2025-04-19T20:17:30.090Z (about 1 year ago)
- Topics: android-library, android-service, fadecandy, fadecandy-server, led-controlling
- Language: Kotlin
- Homepage: https://bertrandmartel.github.io/fadecandy-android
- Size: 5.75 MB
- Stars: 25
- Watchers: 7
- Forks: 3
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Fadecandy Android
[](https://circleci.com/gh/bertrandmartel/fadecandy-android)
[  ](https://bintray.com/bertrandmartel/maven/fadecandy-server-android/_latestVersion)
[](https://maven-badges.herokuapp.com/maven-central/fr.bmartel/fadecandy-service)
[](http://javadoc-badge.appspot.com/fr.bmartel/fadecandy-service)
[](LICENSE.md)
The [Fadecandy](https://github.com/scanlime/fadecandy) server library for Android devices
Control your Fadecandy USB LED controller plugged into your Android device
Try Fadecandy server / client with the [sample app](https://play.google.com/store/apps/details?id=fr.bmartel.fadecandy) available on the Playstore.
**No root required**
[](https://play.google.com/store/apps/details?id=fr.bmartel.fadecandy)
You can control your Fadecandy device from :
* Android smartphone
* Android tablet
* Android TV (the sample app is not available on Android TV Playstore but you can upload the apk anyway)
## What is Fadecandy ?
Fadecandy is a USB controlled LED driver with on-board dithering. One Fadecandy device support up to 8 strips of 64 Leds that gives you a maximum of 512 Leds/Fadecandy device.
Check [official Fadecandy repository](https://github.com/scanlime/fadecandy) for more information about Fadecandy device
## What is Fadecandy Server ?
Fadecandy server is a TCP server embedded in Fadecandy project which is used to remotely control Fadecandy USB devices through [Open Pixel Control protocol](http://openpixelcontrol.org/), a custom TCP protocol tailored to control LEDs
Check [official Fadecandy repository](https://github.com/scanlime/fadecandy#open-pixel-control-server) for more information about Open Pixel Control Server
## How does it work ?
Fadecandy Android fork is available at https://github.com/bertrandmartel/fadecandy
Originally, Fadecandy server uses libusbx to interface with Fadecandy USB devices. In Android, a regular user has to grant permission for the application to open an USB device.
Using [Fadecandy Android app](https://play.google.com/store/apps/details?id=fr.bmartel.fadecandy), when you plug a Fadecandy in your Android device, you will see this pop-up :
If user click on `Use by default for this USB device`, it wont be asked again for this USB device when the device is re-plugged again.
What differs between libusbx Fadecandy server & Android Fadecandy server is that All USB operations including USB attached/detached events are catch using Java API :
* start server flow :
| order | description | language |
|---|--------------------------------------------------------------------------|-------|
| 1 | register a USB event receiver (for a specific product/vendor ID) | Kotlin |
| 2 | start Fadecandy server | C++ |
* USB attached flow :
| order | description | language |
|---|--------------------------------------------------------------------------|-------|
| 1 | catch a USB device attached event | Kotlin |
| 2 | check if this Fadecandy USB is allowed | Kotlin |
| 3 | ask permission if device is not allowed | Kotlin |
| 4 | open the device if permission is granted | Kotlin |
| 5 | notify Fadecandy server that a new device is attached | C++ |
* USB detached flow :
| order | description | language |
|---|-------------------|--------|
| 1 | catch a USB device detached event | Kotlin |
| 2 | notify Fadecandy server that a device is detached | C++ |
* USB write flow :
| order | description | language |
|-------|-------------|----------|
| 1 | prepare data to be written | C++ |
| 2 | perform a bulk transfer on `UsbDeviceConnection` | Kotlin |
For writing to USB device, Fadecandy server is calling from C++ a Kotlin method to perform a bulk transfer
## How to include it in your Android project ?
* with Gradle, from jcenter :
```gradle
compile 'fr.bmartel:fadecandy-service:1.62'
```
## How to use it ?
* Use `FadecandyClient` service wrapper :
```java
mFadecandyClient = new FadecandyClient(mContext,
new IFcServerEventListener() {
@Override
public void onServerStart() {
// server is started
}
@Override
public void onServerClose() {
// server is closed
}
@Override
public void onServerError(ServerError error) {
// a server error occured
}
}, new IUsbEventListener() {
@Override
public void onUsbDeviceAttached(UsbItem usbItem) {
// a Fadecandy device has been attached
}
@Override
public void onUsbDeviceDetached(UsbItem usbItem) {
// a Fadecandy device has been detached
}
},
"com.your.package/.activity.MainActivity"
);
```
`FadecandyClient` will give you an easy-to-use interface between Fadecandy Service and your application
### Start Fadecandy server
```java
mFadecandyClient.startServer();
```
`startServer()` will internally stop the server if already running before starting
### Start Fadecandy server with custom server config
```java
mFadecandyClient.startServer(yourConfig);
```
Fadecandy server configuration is a JSON document, check [server config doc](https://github.com/scanlime/fadecandy/blob/master/doc/fc_server_config.md)
### Stop Fadecandy server
```java
mFadecandyClient.closeServer();
```
### Check if server is running
```java
boolean isRunning = mFadecandyClient.isServerRunning();
```
### Get last server IP/host & last server port
```java
String serverAdress = mFadecandyClient.getIpAddress();
int serverPort = mFadecandyClient.getServerPort();
```
### Set server IP/host & server port
```java
mFadecandyClient.setServerAddress("127.0.0.1");
mFadecandyClient.setServerPort(7890);
```
You will need to call `startServer()` to restart the server after modifying these parameters
### Set server configuration
```java
mFadecandyClient.setConfig(myConfig);
```
Fadecandy server configuration is a JSON document, check [server config doc](https://github.com/scanlime/fadecandy/blob/master/doc/fc_server_config.md)
### Get list of Fadecandy USB devices attached
```java
HashMap usbDevices = mFadecandyClient.getUsbDeviceMap();
```
The key is the USB device file descriptor, The value is an `UsbItem` object encapsulating :
| Class | description |
|-------------|----------------|
| `UsbDevice` | features attached USB device |
| `UsbConnection` | send/receive data from an UBS device |
| `UsbEndpoint` | channel used for sending/receiving data |
### Get Fadecandy server configuration
```java
String config = mFadecandyClient.getConfig();
```
Fadecandy configuration is composed of the Top level object defined in [Fadecandy Server configuration documentation](https://github.com/scanlime/fadecandy/blob/master/doc/fc_server_config.md#top-level-object)
### Set Fadecandy service type
* Set the Fadecandy service as `PERSISTENT` (default value) which means the service will stay in background, a notification will be present in notification view. The user can kill the service by clicking on "close background service" on the notification :
```java
mFadecandyClient.setServiceType(ServiceType.PERSISTENT_SERVICE);
```
* Set the Fadencandy service as `NON_PERSISTENT`. The service will be killed as soon as no application is bound to it
```java
mFadecandyClient.setServiceType(ServiceType.NON_PERSISTENT_SERVICE);
```
### Bind Fadecandy service without starting server
```java
mFadecandyClient.connect();
```
### Unbind Fadecandy service
```java
mFadecandyClient.disconnect();
```
Assure you call `disconnect()` to close service & unregister client receiver when you are done with Fadecandy Service (eg exit your application)
### Proguard
If you are using proguard add this to your `proguard-rules.pro` :
```proguard
-keep class fr.bmartel.android.fadecandy.service.FadecandyService { *; }
-keepclassmembers,allowobfuscation class fr.bmartel.android.fadecandy.service.FadecandyService.** {
;
}
```
This will keep methods in `FadecandyService` to preserve calls from native code to this class
## Build Library
### Get source code
```bash
git clone git@github.com:bertrandmartel/fadecandy-android.git
cd fadecandy-android
git submodule update --init --recursive
```
### Build
```bash
./gradlew build
```
## Open Source components
### Fadecandy Service
* Fadecandy : https://github.com/scanlime/fadecandy
* rapidjson : https://github.com/scanlime/rapidjson
* libwebsockets : https://github.com/bertrandmartel/libwebsockets
* Android support-v4
### Fadecandy Application
* DiscreteSeekBar : https://github.com/AnderWeb/discreteSeekBar
* Android Holo ColorPicker : https://github.com/LarsWerkman/HoloColorPicker
* Open Pixel Control Library : https://github.com/bertrandmartel/opc-java
* AndroidAsync : https://github.com/koush/AndroidAsync
* Ace editor : https://github.com/ajaxorg/ace
* JS Beautifier : https://github.com/beautify-web/js-beautify
* Led Icon by Kenneth Appiah, CA (Pulic Domain) : https://thenounproject.com/search/?q=led&i=3156
* appcompat-v7, design & recyclerview-v7
## License
```
The MIT License (MIT) Copyright (c) 2016-2018 Bertrand Martel
```