Skip to main content

Cloud Control API

The XXTouch Elite Cloud Control API is developed using the WebSocket protocol, with a built-in cloud control client called elfclient.

We also provide a cloud control server example XXTouch-CloudControl, which you can customize according to your business needs.

CloudControl.001

You need to configure the cloud control server address for the elfclient client. Once the client successfully connects to the WebSocket server, the server can communicate with the device following the specifications below.

Specification​

Request​

{
  "type": "Message Type",
  "body": "Message Data"
}

Response​

{
  "type": "Message Type",
  "body": "Message Data",
  "error": "Empty if successful, error message if failed"
}
note

If body contains binary data, it is transmitted using Base64 encoding.

Heartbeat​

After the client connects, the server should periodically send ping to the client at intervals not exceeding 30 seconds (default is 5 seconds). If the client does not receive a ping for more than 30 seconds, it will automatically disconnect and attempt to reconnect.

Server Example Code​

import WebSocket from 'ws'

const wss = new WebSocket.Server({ port: 9000 })

wss.on('connection', (ws) => {
  ws.on('message', (data) => {
    const json = JSON.parse(data)
    if (json.error) {
      console.log('Error:' + json.error)
    } else {
      console.log(json.body)
    }
  })

  setInterval(() => {
    ws.ping(() => {})
  }, 5000)

  ws.send(
    JSON.stringify({
      type: 'app/state',
    }),
  )
})

Get Service Status​

{
  "type": "app/state"
}
{
  "type": "app/state",
  "error": "",
  "body": {
    "app": {
      "version": "Service Version",
      "license": "Expiration Date"
    },
    "script": {
      "select": "Currently Selected Script",
      "running": "Is Running"
    },
    "system": {
      "os": "ios",
      "name": "Device Name",
      "sn": "Device Serial Number",
      "ip": "Device IP Address",
      "battery": "Device Battery Level",
      "log": "Last Log Entry"
    }
  }
}

Activate License Code​

{
  "type": "app/register",
  "body": {
    "code": "12/16-digit Registration Code"
  }
}
{
  "type": "app/register",
  "error": ""
}

Get Script List​

{
  "type": "script/list"
}
{
  "type": "script/list",
  "error": "",
  "body": ["Script1", "Script2"]
}

Run Script​

{
  "type": "script/run",
  "body": {
    "name": "a.lua"
  }
}
{
  "type": "script/run",
  "error": ""
}

Stop Script​

{
  "type": "script/stop"
}
{
  "type": "script/stop",
  "error": ""
}

Encrypt Script​

{
  "type": "script/encrypt",
  "body": {
    "name": "a.lua"
  }
}
{
  "type": "script/encrypt",
  "error": ""
}

Get Script​

{
  "type": "script/get",
  "body": {
    "name": "a.lua"
  }
}
{
  "type": "script/get",
  "error": "",
  "body": "Base64-encoded Script Content"
}

Update Script​

{
  "type": "script/put",
  "body": {
    "name": "a.lua",
    "data": "Base64-encoded Script Content"
  }
}
{
  "type": "script/put",
  "error": ""
}

Delete Script​

{
  "type": "script/delete",
  "body": {
    "name": "a.lua"
  }
}
{
  "type": "script/delete",
  "error": ""
}

Get Logs​

{
  "type": "system/log/get",
  "body": {
    "last": 5
  }
}
{
  "type": "system/log/get",
  "error": "",
  "body": "Logs"
}

Delete Logs​

{
  "type": "system/log/delete"
}
{
  "type": "system/log/delete",
  "error": ""
}

Reboot Device​

{
  "type": "system/reboot"
}
{
  "type": "system/reboot",
  "error": ""
}

Respring Device​

{
  "type": "system/respring"
}
{
  "type": "system/respring",
  "error": ""
}

Get Screenshot​

{
  "type": "screen/snapshot",
  "body": {
    "format": "png",
    "scale": 100
  }
}
{
  "type": "screen/snapshot",
  "error": "",
  "body": "Base64-encoded Screenshot Data"
}

Finger Down​

{
  "type": "touch/down",
  "body": {
    "finger": 1,
    "x": 100,
    "y": 100
  }
}
{
  "type": "touch/down",
  "error": ""
}

Finger Move​

{
  "type": "touch/move",
  "body": {
    "finger": 1,
    "x": 100,
    "y": 100
  }
}
{
  "type": "touch/move",
  "error": ""
}

Finger Up​

{
  "type": "touch/up",
  "body": {
    "finger": 1
  }
}
{
  "type": "touch/up",
  "error": ""
}

Key Down​

{
  "type": "key/down",
  "body": {
    "code": "HOMEBUTTON",
  }
}
{
  "type": "key/down",
  "error": ""
}

Key Up​

{
  "type": "key/up",
  "body": {
    "code": "HOMEBUTTON",
  }
}
{
  "type": "key/up",
  "error": ""
}

All APIs in this section must provide a path parameter, with the value starting from the /var/mobile/Media/1ferver directory.

File List​

{
  "type": "file/list",
  "body": {
    "path": "/lua/scripts"
  }
}
{
  "type": "file/list",
  "error": "",
  "body": [
    { "name": "a", "type": "dir" },
    { "name": "b", "type": "file" }
  ]
}

Download File​

{
  "type": "file/get",
  "body": {
    "path": "/lua/scripts/a.dat"
  }
}
{
  "type": "file/get",
  "error": "",
  "body": "Base64-encoded File Content"
}

Upload File​

{
  "type": "file/put",
  "body": {
    "path": "/lua/scripts/a.dat",
    "data": "Base64-encoded File Content"
  }
}
{
  "type": "file/put",
  "error": ""
}

Create Directory​

{
  "type": "file/put",
  "body": {
    "path": "/dir",
    "directory": true
  }
}
{
  "type": "file/put",
  "error": "",
  "body": {
    "directory": true
  }
}

Delete File or Directory​

{
  "type": "file/delete",
  "body": {
    "path": "/scripts/a.lua"
  }
}
{
  "type": "file/delete",
  "error": ""
}