SDK Access

All Robots Except a Few Older Models Use the Same SDK

The robots now share a single, unified SDK, which is included in the demo program. Download the demo program and copy the SDK library file from its libs folder.

Sample Code

Demo program download: Click to download

Note: For the SDK used in the demo, download the jar that matches the robot’s system from the releases page.

Configure the default launch app

Configure the Manifest file

<activity android:name=".MainActivity">
    <intent-filter>
        <action android:name="android.intent.action.MAIN"/>
        <category android:name="android.intent.category.LAUNCHER"/>
     </intent-filter>
     <intent-filter>
         <action android:name="action.orionstar.default.app" />
         <category android:name="android.intent.category.DEFAULT" />
     </intent-filter>
</activity>

If the app needs to launch by default after the robot boots, configure the following in the Manifest

<intent-filter>
    <action android:name="action.orionstar.default.app" />
    <category android:name="android.intent.category.DEFAULT" />
</intent-filter>

Then set it in Settings (swipe down with three fingers and tap Settings) – Developer Settings – Boot Apps

Note: The Boot Apps setting was officially released in OTA3

Permissions

For full SDK integration, declare the following permissions in AndroidManifest.xml

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="com.ainirobot.coreservice.robotSettingProvider" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>

SDK Access

1. Create a callback for receiving voice requests and system events

public class ModuleCallback extends ModuleCallbackApi {
    @Override
    public boolean onSendRequest(int reqId, String reqType, String reqText, String reqParam)
            throws RemoteException {
        //Receive voice commands
        //reqTyp : Voice command type
        //reqText : Speech recognition text
        //reqParam : Voice command parameters
        return true;
    }
    @Override
    public void onRecovery()
            throws RemoteException {
           //Control is restored. After receiving this event, resume control of the robot

    }
    @Override
    public void onSuspend()
            throws RemoteException {
           //Control has been taken away by the system. After receiving this event, all API calls are invalid

    }

2. Connect to the server

RobotApi.getInstance().connectServer(this, new ApiListener() {
    @Override
    public void handleApiDisabled() {
    }
    @Override
    public void handleApiConnected() {
        //Server connected. Set the callback for receiving requests, including voice commands, system events, etc.
        RobotApi.getInstance().setCallback(new ModuleCallback());
    }
    @Override
    public void handleApiDisconnected() {
        //Disconnected
    }
});

Initializing the robot SDK means the robot hands over control of the chassis capabilities to the app that is currently running. The robot triggers the disconnected callback when the system takes over, when a fault occurs, or when another program that uses the robot SDK is started. Of these, the connection is re-established only when the system takeover ends.

Note 1: All APIs can be called only after the connection to the server succeeds

Note 2: Only a foreground process running in the foreground can connect correctly and obtain control of the robot chassis. Service processes do not work.

3. Set the callback

RobotApi.getInstance().setCallback(new ModuleCallback());

4. Finish the command

RobotApi.getInstance().finishModuleParser(reqId, result);

After a received request or voice command has been processed, call finishModuleParser to finish the command. reqId is obtained from the onSendRequest callback, and result is the execution result.

5. Register a status listener

StatusListener statusListener = new StatusListener(){
    @Override
    public void onStatusUpdate(String type, String data) throws RemoteException {
    };
}
//Register the status listener
RobotApi.getInstance().registerStatusListener(type, statusListener);
//Unregister the status listener
RobotApi.getInstance().unregisterStatusListener(statusListener);

type is the status type to listen for. The following types are supported:

• Definition.STATUS_POSE: The robot’s current coordinates, reported continuously
• Definition.STATUS_POSE_ESTIMATE: The current localization status, reported when the localization status changes
• Definition.STATUS_BATTERY: Current battery status information, including whether it is charging, the battery level, whether there is a low-battery warning, and so on

6. Set reqId

Many SDK methods take a reqId parameter, an ID used for debugging and tracing logs. Any number works for the function to run normally, but for easier log tracing and debugging, we recommend making reqId an auto-incrementing static variable, or passing different reqId values to distinguish function calls according to your business needs.

How to Launch an APK Correctly

To make sure the APK is correctly authorized by the robot chassis and can use the robot’s features, launch it from RobotOS Home (see the video below). If you want an APK to launch at boot, simply set “Boot Apps” in Settings.

Note: A program run directly from the IDE and opened on the robot has no permissions. It gets permissions only when launched by tapping its icon in the Application Center (Home) or by auto-launch at boot.

FAQ

1. API calls return a resource conflict

For the hardware-related APIs in the SDK, using two APIs to operate the same component at the same time causes a resource conflict. For example, while the robot is navigating, you cannot use the turn-left/turn-right APIs.

2. Robot screen resolution

GreetingBot	GreetingBot Mini	LuckiBot	BigScreenBot
1200×1920	1920×1080	1200×1920	Upper screen 1200×1920 Lower screen 1080×1920