fadecandy-server-android

Fadecandy server for Android

License

License

GroupId

GroupId

fr.bmartel
ArtifactId

ArtifactId

fadecandy-service
Last Version

Last Version

1.62
Release Date

Release Date

Type

Type

aar
Description

Description

fadecandy-server-android
Fadecandy server for Android
Project URL

Project URL

https://github.com/bertrandmartel/fadecandy-android
Source Code Management

Source Code Management

https://github.com/bertrandmartel/fadecandy-android

Download fadecandy-service

How to add to project

<!-- https://jarcasting.com/artifacts/fr.bmartel/fadecandy-service/ -->
<dependency>
    <groupId>fr.bmartel</groupId>
    <artifactId>fadecandy-service</artifactId>
    <version>1.62</version>
    <type>aar</type>
</dependency>
// https://jarcasting.com/artifacts/fr.bmartel/fadecandy-service/
implementation 'fr.bmartel:fadecandy-service:1.62'
// https://jarcasting.com/artifacts/fr.bmartel/fadecandy-service/
implementation ("fr.bmartel:fadecandy-service:1.62")
'fr.bmartel:fadecandy-service:aar:1.62'
<dependency org="fr.bmartel" name="fadecandy-service" rev="1.62">
  <artifact name="fadecandy-service" type="aar" />
</dependency>
@Grapes(
@Grab(group='fr.bmartel', module='fadecandy-service', version='1.62')
)
libraryDependencies += "fr.bmartel" % "fadecandy-service" % "1.62"
[fr.bmartel/fadecandy-service "1.62"]

Dependencies

compile (1)

Group / Artifact Type Version
com.android.support » support-v4 jar 27.0.2

runtime (1)

Group / Artifact Type Version
org.jetbrains.kotlin : kotlin-stdlib-jre7 jar 1.2.21

Project Modules

There are no modules declared in this project.

Fadecandy Android

CircleCI Download Maven Central Javadoc License

The 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 available on the Playstore.

No root required

Download Fadecandy from Google Play

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.

notif

Check official Fadecandy repository 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, a custom TCP protocol tailored to control LEDs

Check official Fadecandy repository 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, when you plug a Fadecandy in your Android device, you will see this pop-up :

notif

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 :
compile 'fr.bmartel:fadecandy-service:1.62'

How to use it ?

  • Use FadecandyClient service wrapper :
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

mFadecandyClient.startServer();

startServer() will internally stop the server if already running before starting

Start Fadecandy server with custom server config

mFadecandyClient.startServer(yourConfig);

Fadecandy server configuration is a JSON document, check server config doc

Stop Fadecandy server

mFadecandyClient.closeServer();

Check if server is running

boolean isRunning = mFadecandyClient.isServerRunning();

Get last server IP/host & last server port

String serverAdress = mFadecandyClient.getIpAddress();

int serverPort = mFadecandyClient.getServerPort();

Set server IP/host & server port

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

mFadecandyClient.setConfig(myConfig);

Fadecandy server configuration is a JSON document, check server config doc

Get list of Fadecandy USB devices attached

HashMap<Integer, UsbItem> 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

String config = mFadecandyClient.getConfig();

Fadecandy configuration is composed of the Top level object defined in Fadecandy Server configuration documentation

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 :
mFadecandyClient.setServiceType(ServiceType.PERSISTENT_SERVICE);

notif

  • Set the Fadencandy service as NON_PERSISTENT. The service will be killed as soon as no application is bound to it
mFadecandyClient.setServiceType(ServiceType.NON_PERSISTENT_SERVICE);

Bind Fadecandy service without starting server

mFadecandyClient.connect();

Unbind Fadecandy service

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 :

-keep class fr.bmartel.android.fadecandy.service.FadecandyService { *; }

-keepclassmembers,allowobfuscation class fr.bmartel.android.fadecandy.service.FadecandyService.** {
    <methods>;
}

This will keep methods in FadecandyService to preserve calls from native code to this class

Build Library

Get source code

git clone [email protected]:bertrandmartel/fadecandy-android.git
cd fadecandy-android
git submodule update --init --recursive

Build

./gradlew build

Open Source components

Fadecandy Service

Fadecandy Application

License

The MIT License (MIT) Copyright (c) 2016-2018 Bertrand Martel

Versions

Version
1.62
1.61
1.6
1.4