JS API & REST API quick Start

JS API & REST API quick start

Foreword

Before introducing this section, let's do some preparatory work, that is, download and install Total Control software on our official website.

JS API & REST API review

JS API & REST API are a series of script automation interfaces provided by Total Control that allow operation on one device or multiple devices.

JS API
The Total Control script is written in the JavaScript language, and any text editing tool, such as Notepad, can be used to develop Total Control scripts.
REST API
The Total Control REST API is designed with a RESTful web services framework based on the original Total Control JS API and supports any scripting language: Java, Node JS, Python, Ruby, C/C++, etc. Support various operating systems: Android, iOS, Windows, macOS.

Device object

When the Total Control software is connected to the device (click the Connect button or auto connect), an object is created that contains all device-related properties and functions to perform operations/inputs on the device. Once the device is disconnected, the object will be destroyed. Each device has an object. The object identifier of the device is the device ID. The device ID format is “device@ <10 digits>”.

JS API detailed

The script requires a device ID to perform a query or operation on the device, and Device.searchObject() provides various methods for getting a single device ID or multiple device IDs. For properties associated with device IDs, see JS API manual and REST API manual, there are two types of features:

Function applied to a single device
Function applied to multiple devices

The device ID is a string and the device list is an array. The JS API uses "device." for individual device operations or "devices." for device list operations (multiple devices can be executed simultaneously). Use "device." for device property acquisition. Note that these property values are the real properties of the corresponding mobile device. They are read-only and cannot be changed, because the properties of each mobile device may be different. So device attribute values are only for a single device object. E.g,

var device = Device.getMain();  //Get the current master device object
var devices = Device.searchObject(sigmaConst.DevAll); //Get all devices currently connected

 //Operation of equipment
device.click(0.100, 0.100);          // Click the relative coordinates 0.100, 0.100 on the main device
devices.click(0.100, 0.100);         // Click on the coordinates 0.100, 0.100 on all connected devices

//Get device attribute value
device.IP;     // IP address of the device
device.DPI;   // The pixel size of the device screen
device.IMEI;  // The IMEI number of the device

REST API detailed

Most JS APIs have their own REST APIs, so we can operate on single or multiple devices with two different interfaces. See the for more interfaces.

For example, close the JS API of the app with the specified package name and its corresponding REST API:

Device.closeApp(packageName)
http://IP:8090/TotalControl/v1/devices/:device/apps/:packageName
Request method: POST

The REST API address starts with " http://IP:8090/TotalControl/v1/devices". To get the device object, you must first obtain the development token used by Total Control script development (REST API authentication mechanism, request method: GET, http: //IP: 8090/TotalControl/v1/login), then get the device object, and finally the device object operation.

For single device operation, the url format is:
For multi-device operations, the url format is:

For example, text input to the focus input box in the device, where text is the input text content

//Single device operation
http://IP:8090/TotalControl/v1/devices/device=:device/screen/texts
{
"token":"270eq7lXQK8bXYsJ",
"text":"33333",
}
//Multi-device operation
http://IP:8090/TotalControl/v1/devices/ids/screen/texts
{
"token":"270eq7lXQK8bXYsJ",
"text":"33333",
"ids":["device@1116106541","device@1116106541"]
}

JS and REST API methods for getting device objects

We can get the device object of the mobile phone in a variety of ways, and we can get both a single device object and a collection of device objects.

The following we introduce several methods of the JS API and its corresponding REST API to get device objects. Not all JS APIs get device objects have corresponding REST APIs (REST API gets device request request method GET):

//(single device) Get the current master device object
Device.getMain()
http://IP:8090/TotalControl/v1/devices/main?token=:token
//(single device) Get device object by given device name
Device.searchObject()
http://IP:8090/TotalControl/v1/devices?name=:name&token=:token
//(single device) Get device object by given device serial number
Device.searchObject(sigmaConst.DevSerial,)
//(multi-device) Get the object collection of all devices currently connected to Total Control
Device.searchObject(sigmaConst.DevAll)
http://IP:8090/TotalControl/v1/devices?q=all&token=:token
//(multi-device) Get the object collection of all devices in the group according to the given group name
Device.searchObject(sigmaConst.DevGroup, )
http://IP:8090/TotalControl/v1/devices?q=group&name=:name&token=:token
//(Single device) After running the script, a device selection box pops up, and device object acquisition is performed according to the selected device.
Device.searchObject(sigmaConst.DevSelectOne)
//(Multi-device) After running the script, a device selection box pops up, and the device object collection is obtained according to the selected multiple devices.
Device.searchObject(sigmaConst.DevSelectMult)
//(Multi-device) After running the script, a device group selection window pops up, and the object collection of all devices in the group is obtained according to the selected one device group.
Device.searchObject(sigmaConst.DevSelectGroup)

How to use the REST API

Here we use the Total Control JS API "TCHttpRequest" to explain how to use the REST API. For more information on the TCHttpRequest interface, please refer to the JS API manual. The steps of the REST API for device operation are as follows:

1. Base64 encoded username and password

Open the Total Control software and find the account information of the REST API in the REST API column of the system settings (as shown in the figure below). Of course, the username and password can be changed to other ones according to personal preference. The username and password are used to establish a connection with the token. To get the token, you need to encode the username and password in Base64.

The username and password (username:password) are assembled for base64 encoding to generate a string. Users can encode their usernames and passwords in Base64 according to their own code language. You can also use this tool, http://tool.oschina.net/encrypt?type=3, enter "sigma:3D391497" in the plaintext and click BASE64 encoding to get the BASE64 encoded value "c2lnbWE6M0QzOTE0OTc=".

2. Get the development token used by Total Control script development

Request method: GET

http://IP:8090/TotalControl/v1/login

//Here "c2lnbWE6M0QzOTE0OTc=" is the BASE64 encoded value obtained in step one.
var res = TCHttpRequest("http://localhost:8090/TotalControl/v1/login","GET",{Authorization:" c2lnbWE6M0QzOTE0OTc="},"",2000);
//Use content to output content
 print(res.content);

Return result

//The token value obtained is" OEPux5xceiyIGO6r"
{"status":true,"value":{"token":" OEPux5xceiyIGO6r"}}

3. REST API get device object

There are many ways to get device objects from the REST API. The request method is GET. Please see the article "Get Device Object Method" in the article. The token here is the token value "OEPux5xceiyIGO6r" obtained in the second step. IP is the IP address.

//Get the current master device object, return value: device object, {"id":"device@-230441652"}, the corresponding JS API is Device.getMain()
TCHttpRequest("http://IP:8090/TotalControl/v1/devices/main?token=:token","GET",{},"",2000);

4. REST API action device object

Send a click event to the coordinates (100, 200), request mode POST, where device is the value obtained in step 3, token is the value obtained in step 2, x, y is the coordinate value that the REST API needs to fill, and state indicates click (press + bounce)

//Send a click event, the corresponding JS API is device.click(x, y, state);
http://IP:8090/TotalControl/v1/devices/device@-230441652/screen/inputs
{
    "token":"270eq7lXQK8bXYsJ",
    "x":100,
    "y":200,
    "state":"press"
}

JS API interface usage example

Open the QQ music software on your phone with the JS API

//Get device object
var device = Device.getMain();
//Open QQ music with runApp(AppName)
var runapp=device.runApp("com.tencent.qqmusic");
if (runapp == 0){
    print("Successfully opened QQ music software");
} else{
    print(lastError());
}

Operation result

//When the QQ music software on the phone is successfully opened, the output is:：
Successfully opened QQ music software
//Output error message when opening QQ music software fails

REST API interface usage example

REST API implement open QQ music software on your phone

#!/user/bin/python
#-*- coding:utf-8 -*-

import urllib.parse
import urllib
import http.client
import json
import urllib.parse
import base64
import time
from argparse import Namespace

#Define some basic variables
REST_CONN = 'localhost:8090'
REST_BASIC_PATH = 'http://' + REST_CONN + '/TotalControl/v1/'
conn = http.client.HTTPConnection(REST_CONN)
user_pass = 'sigma:3D391497'

#Define the get token method
#Request method: GET，http://IP:8090/TotalControl/v1/login 
def login(conn,key):
    request_url = REST_BASIC_PATH + "login"
    header = {'Authorization':key}
    conn.request(method="GET", url=request_url, headers=header)
    response = conn.getresponse()
    res = response.readline()
    return res
#Defining methods for getting device objects
#Request method: GET，http://IP:8090/TotalControl/v1/devices/main 
def getMain(conn,token):
    request_url = REST_BASIC_PATH + "devices/main?token="+token
    conn.request(method="GET", url=request_url)
    response = conn.getresponse()
    res = response.readline()
    resp = json.loads(res)
    main = resp['id']
    return main
#Define how to open the software
#Request method: POST，http://IP:8090/TotalControl/v1/devices/:device/apps/:packageName 
def runApp(conn,deviceId,appName,state,token):
    request_url = REST_BASIC_PATH + "devices/" + deviceId + "/apps/" + appName
    body={'state':state,'token':token}
    body=json.dumps(body).encode(encoding='utf-8')
    conn.request(method="POST",url=request_url,body=body)
    response = conn.getresponse()
    res = response.readline()
    return res

print("Step 1: Base64 encoded username and password")
encodeStr=base64.b64encode(user_pass.encode("UTF-8"))
print("The Base64 encoded value is:" ,encodeStr)
print("Step 2: Get the token")
#Json.loads is used to decode JSON data
res=login(conn,encodeStr)
resp = json.loads(res)
token=resp['value']['token']
print("The token obtained is:",token)
print("Step 3: Get the device object")
deviceId=getMain(conn,token)
print("The obtained device object is:",deviceId)
print("Step 4: Open QQ music software")
ret = runApp(conn,deviceId,"com.tencent.qqmusic","active",token)
ret_json = json.loads(ret)
print(ret_json)
#Sleep for five seconds
time.sleep(5)

Operation result

Step 1: Base64 encoded username and password
Base64 encoded values are: b'c2lnbWE6M0QzOTE0OTc='
Step 2: Get the token
The token obtained is: cSb8XU8JQAk85X7d
Step 3: Get the device object
The obtained device object is: device@-230441652
Step 4: Open QQ music software
{'status': True, 'value': 'make it active.'}