Atom Nucleus Mobile SDK

From Atomation's Wiki
Jump to: navigation, search

Atomation’s mobile SDK is already integrated with Atomation's Hardware SDK wrapping it with a friendly API. The SDK will let you take advantage of all features included in the Hardware SDK (i.e. IMU, Temperature, Humidity, ADC read, RGB Led lighting, Motor controller, Transistors, Relays and more!). All can be easily controlled and the specific functions are up to you.

Getting Atomation's SDK


Visit the Atomation website and click on Download SDK tab.

Login at Atomation

After registration, Login at the Atomation website and reach the Admin. On the Admin Home Page, you will find instructions and guidelines.

Add your Application

Once you have logged in you should start defining your first app:

Your application's name.
A brief description of your application.
The name of the application package (from the IDE).

Adding the SDK and Setting the Token

Add the following line to Module-level /app/build.gradle before dependencies:

repositories {

Add the compile dependency in the build.gradle file:

 compile 'net.atomation:sdk:1.0.0' 

Add a meta-data element to the application element in the AndroidManifest.xml file:

<application android:label="@string/app_name" ...>
    <meta-data android:name="net.atomation.Token" android:value="ExampleToken" />

The meta-data value (ExampleToken) is Atomation's Token. The Token can be found in the center column in My Applications.


Atom Nucleus (the controller of the HW SDK) uses BLE to communicate with the mobile device. To work with this protocol you need to know and understand a few terms:

The Mobile device, that handles the communication.
The Hardware SDK.
MAC Address 
A six byte hex number which represents a physical address of the device, two devices cannot share the same MAC Address.
Received Signal Strength Indicator, how powerful a signal is, measured in Dbm.
A state that the peripheral advertises itself when not connected.
Device Name 
The name advertised by the peripheral.
The way to send information to the peripheral device.
The way to get data once (for each read) from the peripheral.
Non stop reads, after enabling it, it is sent automatically from the peripheral.

Crearting Your First Atom

Atoms are the objects that represent Atom Nucleus and any additional skins. While working with Atomation's SDK you need to use three objects:


This objects manages all objects. It creates, saves and retrieves Nucleus Objects.

NucleusAtomManager is a Singlton you only need to connect it once:

    NucleusAtomManager manager = NucleusAtomManager.getInstance(context);


This object represents Nucleus, the data is read from it and written to it.

The way to create it is:

   IMultiSenseAtom atom = manager.getMultiSenseDevice(macAddress);

    if (atom == null) {
        atom = manager.createMultiSenseDevice(macAddress);

The "macAddress" parameter is a String that represents the MAC address of the desired MultiSense (for example, "80:30:DC:0C:EA:EC").


This object is responsible for handling and managing the BLE scan actions. The main goal of scan is to find the advertising peripherals.

To use this object you need to:

    ScanHelper scanHelper = ScanHelper.getInstance(context);


The SDK adds these permissions to your application:

    <uses-permission android:name="android.permission.BLUETOOTH"/>
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>

Android Marshmellow (6.0) Permissions Mechanism

The following permissions are marked as dangerous since Android Marshmellow and must be granted by the user specifically.

    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

These permissions are needed in order to initiate a BLE scan, therefore the SDK will request these when the developer starts a scan. If the user does not grant these permissions, the scan will fail and onScanError callback will be called with the USER_NOT_GRANTED_LOCATION_PERMISSIONS error code.



The scanning action is performed to see which peripheral devices are around the central. The methods used for scanning and scanning actions can be found in ScanHelper.


To communicate with the peripheral device you need to connect to it. The scan action is performed on the Atom object:


It is recommended to start a scan action before a connection action.

Sensors and Actuators

You can add to Atomation's Nucleus more Skins, each Skin has different capabilities, for the complete list please search Hardware Kits here. In each article regarding Skins you can find more information and the relevant code.

Writing Data to the Database

Every read, alert and configuration action is automatically uploaded to the database. If you want to upload any other data you can do it using the sendEvent method from the IMultiSenseAtom object. Send event method:

sendEvent(String event, String type, String data)
Name Type Description
event String A String that will be sent to the Data Base, it is recommended to send the kind of event (for example, TempratureAlert).
type String A String that will be sent to the Data Base, it is recommended to send the a description of what happened (for example, HighTemp).
data String A String that will be sent to the Data Base, it is recommended to send the actual numbers (for example, 60).


Atomation's report system will let you explore the data with a friendly interface. The data is divided to different parameters on a timeline and can be exported to third party formats (including Excel, XML, JSON and more). Reports can be found in My Applications.