Difference between revisions of "REST Push API"

From A-SMIL.org
Jump to: navigation, search
(→‎POST oauth2/token)
(→‎POST hardware/display)
 
(32 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
'''Applies to:''' IAdea XMP-2200,XDS-1060,XMP-6200,MBR-1100,XDS-1070 series media appliances
+
'''Applies to:''' IAdea XMP-2200,XDS-1060,XMP-6200,MBR-1100,XDS-1070,XMP-7300 series media appliances
  
 
You may push SMIL scripts and media files into a player using a [http://en.wikipedia.org/wiki/Representational_state_transfer REST] API as documented below.
 
You may push SMIL scripts and media files into a player using a [http://en.wikipedia.org/wiki/Representational_state_transfer REST] API as documented below.
Line 45: Line 45:
 
|-
 
|-
 
| password
 
| password
−
| Password
+
| The password configured on player. Leave this field empty by default.
 
|}
 
|}
  
Line 90: Line 90:
 
! Parameter
 
! Parameter
 
! Function
 
! Function
−
|-
 
−
| access_token
 
−
| Access token returned from ''oauth2/token''
 
 
|-
 
|-
 
| downloadPath
 
| downloadPath
Line 169: Line 166:
 
! Parameter
 
! Parameter
 
! Function
 
! Function
−
|-
 
−
| access_token
 
−
| Access token returned from ''oauth2/token''
 
 
|-
 
|-
 
| seek
 
| seek
Line 206: Line 200:
 
! Parameter
 
! Parameter
 
! Function
 
! Function
−
|-
 
−
| access_token
 
−
| Access token returned from ''oauth2/token''
 
 
|-
 
|-
 
| maxResults
 
| maxResults
Line 244: Line 235:
 
! Parameter
 
! Parameter
 
! Function
 
! Function
−
|-
 
−
| access_token
 
−
| Access token returned from ''oauth2/token''
 
 
|-
 
|-
 
| id
 
| id
Line 274: Line 262:
 
! Parameter
 
! Parameter
 
! Function
 
! Function
−
|-
 
−
| access_token
 
−
| Access token returned from ''oauth2/token''
 
 
|-
 
|-
 
| uri
 
| uri
Line 330: Line 315:
 
! Parameter
 
! Parameter
 
! Function
 
! Function
−
|-
 
−
| access_token
 
−
| Access token returned from ''oauth2/token''
 
 
|-
 
|-
 
| uri
 
| uri
Line 386: Line 368:
 
! Parameter
 
! Parameter
 
! Function
 
! Function
−
|-
 
−
| access_token
 
−
| Access token returned from ''oauth2/token''
 
 
|-
 
|-
 
| mode
 
| mode
Line 419: Line 398:
 
| (Optional) Android intent type
 
| (Optional) Android intent type
 
|}
 
|}
−
 
−
 
  
 
= Management =
 
= Management =
Line 433: Line 410:
 
! Parameter
 
! Parameter
 
! Function
 
! Function
−
|-
 
−
| access_token
 
−
| Access token returned from ''oauth2/token''
 
 
|-
 
|-
 
| id
 
| id
Line 466: Line 440:
 
! Parameter
 
! Parameter
 
! Function
 
! Function
−
|-
 
−
| access_token
 
−
| Access token returned from ''oauth2/token''
 
 
|-
 
|-
 
| id
 
| id
Line 489: Line 460:
 
| input
 
| input
 
| return the current input source being requested to switch to
 
| return the current input source being requested to switch to
 +
|}
 +
 +
== POST hardware/rs232 ==
 +
To send custom serial command through RS232 port, user needs to update RS232 table to define control id with custom serial command, then send custom serial command to external device by predefined control id.
 +
 +
Update RS232 table
 +
 +
'''Input (JSON or multi-part form)'''
 +
 +
{| class="wikitable" border="1"
 +
|-
 +
! Parameter
 +
! Function
 +
|-
 +
| baudrate
 +
| the external RS232 device baud rate setting, e.g. 9600,38400,115200..
 +
|-
 +
| repeatCount
 +
| set default(global) repeat count, defines how many times user like to repeat sending the RS232 command
 +
|-
 +
| repeatInterval
 +
| set default(global) repeat internal while repeat sending RS232 commands if configured
 +
|-
 +
| controls
 +
| defines individual control id and its correspond RS232 command, repeatCount and repeatInterval. When repeatCount and repeatInterval not defined, default setting will be applied
 +
E.g.
 +
'controls':
 +
[{'id':'display.power.on','command':'899s!001','repeatCount':'2','repeatInterval':'200'},
 +
{'id':'display.power.off','command':'899s!000','repeatCount':'1','repeatInterval':'500'}]}
 +
|}
 +
 +
'''Output (JSON)'''
 +
 +
{| class="wikitable" border="1"
 +
|-
 +
! Parameter
 +
! Function
 +
|-
 +
| controls
 +
| returns the control id configured
 +
|-
 +
| repeatInterval
 +
| return the repeat interval configured
 +
|-
 +
| repeatCount
 +
| return the repeat count configured
 +
|-
 +
| baudrate
 +
| return the baud rate configured
 +
|}
 +
 +
send the custom rs232 command by control id
 +
 +
'''Input (JSON or multi-part form)'''
 +
 +
{| class="wikitable" border="1"
 +
|-
 +
! Parameter
 +
! Function
 +
|-
 +
| control
 +
| the predefined control id , e.g. display.power.off
 +
|}
 +
 +
'''Output (JSON)'''
 +
 +
{| class="wikitable" border="1"
 +
|-
 +
! Parameter
 +
! Function
 +
|-
 +
| control
 +
| return the control id sent to external device
 
|}
 
|}
  
Line 501: Line 545:
 
! Parameter
 
! Parameter
 
! Function
 
! Function
−
|-
 
−
| access_token
 
−
| Access token returned from ''oauth2/token''
 
 
|-
 
|-
 
| name
 
| name
Line 509: Line 550:
 
   name for touch buttons: touchButtonN where N = A, B, C, X, Y, Z, L1, L2, R1, R2, …
 
   name for touch buttons: touchButtonN where N = A, B, C, X, Y, Z, L1, L2, R1, R2, …
 
   name for general purpose output: GPOn where n = 0, 1, 2, 3, …
 
   name for general purpose output: GPOn where n = 0, 1, 2, 3, …
−
   name for light-bar on frame: frame
+
   name for LED light-bar on digital signboard: frame
 
|-
 
|-
−
| brightness
+
| brightness  
−
| brightness level: 0...1, set to "0" to turn off light(GPO) ; set to "1" to turn on light(GPO)
+
| brightness level: 0...1, set to "0" to turn off light(GPO) ; set to "1" to turn on light(GPO).
 
|-
 
|-
 
| color
 
| color
−
| color string is common HTML color value, 6-digit hex color code : “#RRGGBB”
+
| color string is common HTML color value, 6-digit hex color code : “#RRGGBB” ;                                                                        To turn off LED, set color code as "#000000".
 +
If the digital signboard supports only 12 bit color input, such as IAdea digital signboard XDS-1078,                                           
 +
signboard will return the supported color code. For example, if set "#FF0000", device will return "#F00000".
 
|}
 
|}
  
Line 548: Line 591:
 
! Parameter
 
! Parameter
 
! Function
 
! Function
−
|-
 
−
| access_token
 
−
| Access token returned from ''oauth2/token''
 
 
|-
 
|-
 
| userPref
 
| userPref
Line 584: Line 624:
 
! Parameter
 
! Parameter
 
! Function
 
! Function
−
|-
 
−
| access_token
 
−
| Access token returned from ''oauth2/token''
 
 
|-
 
|-
 
| commitId
 
| commitId
Line 605: Line 642:
 
| true/false , if restart is required for changes to take effect, restartRequired is true
 
| true/false , if restart is required for changes to take effect, restartRequired is true
 
|}
 
|}
−
 
  
 
== POST/GET task/exportConfigurtion ==
 
== POST/GET task/exportConfigurtion ==
Line 617: Line 653:
 
! Parameter
 
! Parameter
 
! Function
 
! Function
−
|-
+
 
−
| access_token
+
−
| Access token returned from ''oauth2/token''
+
 
|}
 
|}
  
Line 632: Line 666:
 
| return the player configuration { "userPref":[{"value":"", "value";""},{...}...] }
 
| return the player configuration { "userPref":[{"value":"", "value";""},{...}...] }
 
|}
 
|}
−
 
  
 
== POST task/reboot ==
 
== POST task/reboot ==
Line 644: Line 677:
 
! Parameter
 
! Parameter
 
! Function
 
! Function
−
|-
 
−
| access_token
 
−
| Access token returned from ''oauth2/token''
 
 
|}
 
|}
  
Line 670: Line 700:
 
! Parameter
 
! Parameter
 
! Function
 
! Function
−
|-
 
−
| access_token
 
−
| Access token returned from ''oauth2/token''
 
 
|-
 
|-
 
| settings
 
| settings
Line 707: Line 734:
 
! Parameter
 
! Parameter
 
! Function
 
! Function
−
|-
 
−
| access_token
 
−
| Access token returned from ''oauth2/token''
 
 
|-
 
|-
 
| settings
 
| settings
Line 728: Line 752:
 
|-
 
|-
 
| value
 
| value
−
| return the default value configured above  
+
| return the default value configured above
 +
|-
 
| name
 
| name
−
| return name  
+
| return name
 
|}
 
|}
−
 
  
 
== POST security/users/admin ==
 
== POST security/users/admin ==
Line 744: Line 768:
 
! Parameter
 
! Parameter
 
! Function
 
! Function
−
|-
 
−
| access_token
 
−
| Access token returned from ''oauth2/token''
 
 
|-
 
|-
 
| password
 
| password
Line 774: Line 795:
 
! Parameter
 
! Parameter
 
! Function
 
! Function
−
|-
 
−
| access_token
 
−
| Access token returned from ''oauth2/token''
 
 
|}
 
|}
  
Line 802: Line 820:
 
! Parameter
 
! Parameter
 
! Function
 
! Function
−
|-
 
−
| access_token
 
−
| Access token returned from ''oauth2/token''
 
 
|}
 
|}
  
Line 827: Line 842:
 
! Parameter
 
! Parameter
 
! Function
 
! Function
−
|-
 
−
| access_token
 
−
| Access token returned from ''oauth2/token''
 
 
|}
 
|}
  
Line 843: Line 855:
 
! Parameter
 
! Parameter
 
! Function
 
! Function
−
|-
 
−
| access_token
 
−
| Access token returned from ''oauth2/token''
 
 
|}
 
|}
  

Latest revision as of 03:34, 8 January 2016

Applies to: IAdea XMP-2200,XDS-1060,XMP-6200,MBR-1100,XDS-1070,XMP-7300 series media appliances

You may push SMIL scripts and media files into a player using a REST API as documented below.

Naming

The REST API can be accessed via prefix 

http://(device_ip):8080/v2/

appended by API call. For example, for API 

POST oauth2/token

the actual HTTP request should be sent to (device_ip) at port 8080, with content similar to: 

POST /v2/oauth2/token HTTP/1.1
Host: (device_ip)
Content-Type: application/x-www-form-urlencoded;charset=UTF-8

grant_type=password&username=...


Authentication

Before a remote client can access the player, it must authenticate itself by providing the access password set in the player.

POST oauth2/token

Request an access token for API calls.

Input (Multi-part form)

Parameter Function
grant_type Must be the string "password"
username User name requesting access, admin by default
password The password configured on player. Leave this field empty by default.

Output (JSON)

Parameter Function
access_token Authorization token for further API access
token_type Always "Bearer"
expires_in Number of seconds before access_token expires. If this field is returned as an empty string, then the access token does not expire.

Using Access Token

Access token must be sent in the access_token query parameter or an Authorization: Bearer HTTP header.

Request with query parameter GET /v2/path/resource?access_token=access_token HTTP/1.1 HOST: player_ip

Request with HTTP header GET/v2/path/resource HTTP/1.1 HOST: player_ip Authorization: Bearer access_token

Media Transfer

POST files/new

Create a file under http://(device_ip):8080/user-data download path

Input (JSON or multi-part form)

Parameter Function
downloadPath Path of file, must start with prefix /user-data/
data (Optional) File encoded in multipart/form-data
fileSize (Required except when data is provided) Size of file; if provided file can be uploaded in separate chunks
etag (Optional) User-supplied unique string for version identification; default empty string
mimeType (Optional) MIME type of the file; default empty string
modifiedDate (Optional) ISO8601-encoded date time string indicating modified date time; default empty string

Output (JSON)

FileResource structure:

Parameter Function
id String for identifying the file in subsequent operations
downloadPath Path of file to append after http://(device_ip):8080
fileSize Size of file
etag Unique string for version identification
mimeType MIME type of the file
modifiedDate ISO8601-encoded date time string indicating modified date time; default empty string
transferredSize Size uploaded into the player
completed Boolean (true or false) indicating whether file upload has completed

GET files/(id)

Get file information

Input

None

Output (JSON)

FileResource structure

POST files/(id)

Modify a file, may be used to complete an interrupted file transfer operation

Input (JSON or multi-part form)

Parameter Function
seek (Optional) Offset from beginning of file to replace data. Default 0
data (Optional) File encoded in multipart/form-data
downloadPath Path of file, must start with prefix /user-data/
etag (Optional) User-supplied unique string for version identification; default empty string
mimeType (Optional) MIME type of the file; default empty string
modifiedDate (Optional) ISO8601-encoded date time string indicating modified date time; default empty string

Output (JSON)

FileResource structure

POST files/find

List files on the system

Input (JSON or multi-part form)

Parameter Function
maxResults (Optional) Max number of file records to return
pageToken (Optional) Continuation record
query (Optional) Reserved

Output (JSON)

Parameter Function
nextPageToken null of an identifier for report continuation
items Array of FileResource structures

POST files/delete

Delete a file

Input (JSON or multi-part form)

Parameter Function
id ID string of file returned by files/new

Output (JSON)

null

GET (downloadPath)

Retrieve a file


Playback

POST app/exec

Play content once

Input (JSON or multi-part form)

Parameter Function
uri Location of content. May be http://localhost:8080/user-data/...
packageName Android package to launch
className Android class name
action Android action
type (Optional) Android intent type
extras (Optional) Array of Android intent extra parameters

Output (JSON)

Parameter Function
uri Location of content. May be http://localhost:8080/user-data/...
packageName (Optional) Android package to launch
className (Optional) Android class name
action (Optional) Android action
type (Optional) Android intent type

POST app/start

Set default content to play each time player boots up

Input (JSON or multi-part form)

Parameter Function
uri Location of content. May be http://localhost:8080/user-data/...
packageName (Optional) Android package to launch
className (Optional) Android class name
action (Optional) Android action
type (Optional) Android intent type
extras (Optional) Array of Android intent extra parameters

Output (JSON)

Parameter Function
uri Location of content. May be http://localhost:8080/user-data/...
packageName (Optional) Android package to launch
className (Optional) Android class name
action (Optional) Android action
type (Optional) Android intent type

POST app/switch

Switch to play default content

Input (JSON or multi-part form)

Parameter Function
mode Set to "start" to play default content
ifModifiedSince (Optional) Switch to content if it is modified after this ISO8601 date/time

Output (JSON)

Parameter Function
uri Location of content. May be http://localhost:8080/user-data/...
packageName (Optional) Android package to launch
className (Optional) Android class name
action (Optional) Android action
type (Optional) Android intent type

Management

POST hardware/display

Turn On/Off the display

Input (JSON or multi-part form)

Parameter Function
id the display id ,always set to "0" (refer to number zero)
power Set to "on" to turn on display ; Set to "standby" to turn off display

Output (JSON)

Parameter Function
id the display id
power return current display setting

Change display input source to me

Input (JSON or multi-part form)

Parameter Function
id the display id ,always set to "0" (refer to number zero)
input Set to "CEC:me" to switch input source to me ( the player's HDMI input source )

Output (JSON)

Parameter Function
id the display id
input return the current input source being requested to switch to

POST hardware/rs232

To send custom serial command through RS232 port, user needs to update RS232 table to define control id with custom serial command, then send custom serial command to external device by predefined control id.

Update RS232 table

Input (JSON or multi-part form)

Parameter Function
baudrate the external RS232 device baud rate setting, e.g. 9600,38400,115200..
repeatCount set default(global) repeat count, defines how many times user like to repeat sending the RS232 command
repeatInterval set default(global) repeat internal while repeat sending RS232 commands if configured
controls defines individual control id and its correspond RS232 command, repeatCount and repeatInterval. When repeatCount and repeatInterval not defined, default setting will be applied

E.g. 'controls': [{'id':'display.power.on','command':'899s!001','repeatCount':'2','repeatInterval':'200'}, {'id':'display.power.off','command':'899s!000','repeatCount':'1','repeatInterval':'500'}]}

Output (JSON)

Parameter Function
controls returns the control id configured
repeatInterval return the repeat interval configured
repeatCount return the repeat count configured
baudrate return the baud rate configured

send the custom rs232 command by control id

Input (JSON or multi-part form)

Parameter Function
control the predefined control id , e.g. display.power.off

Output (JSON)

Parameter Function
control return the control id sent to external device

POST hardware/light

Control GPO through GPIO board and light bar on digital signboard

Input (JSON or multi-part form)

Parameter Function
name 
 name for touch buttons: touchButtonN where N = A, B, C, X, Y, Z, L1, L2, R1, R2, …
 name for general purpose output: GPOn where n = 0, 1, 2, 3, …
 name for LED light-bar on digital signboard: frame
brightness brightness level: 0...1, set to "0" to turn off light(GPO) ; set to "1" to turn on light(GPO).
color color string is common HTML color value, 6-digit hex color code : “#RRGGBB” ; To turn off LED, set color code as "#000000".

If the digital signboard supports only 12 bit color input, such as IAdea digital signboard XDS-1078, signboard will return the supported color code. For example, if set "#FF0000", device will return "#F00000".

Output (JSON)

Parameter Function
id return interface id
name return interface name
brightness return brightness level
color return color value if available

POST task/importConfigurtion

Import new configuration to player

Input (JSON or multi-part form)

Parameter Function
userPref new configuration object ex. {"userPref": [ {"name": "string", "value": "string" },{...} ] } 
 parameter reference - Device_configuration

Output (JSON)

Parameter Function
commitId return the ID to be committed when commitConfiguration
userPref return newly imported configuration
restartRequired true/false , if restart is required for changes to take effect, restartRequired is true

POST task/commitConfigurtion

Commit new configuration to player

Input (JSON or multi-part form)

Parameter Function
commitId the ID returned when importConfiguration

Output (JSON)

Parameter Function
commitId return the ID just committed
restartRequired true/false , if restart is required for changes to take effect, restartRequired is true

POST/GET task/exportConfigurtion

Get configuration from player

Input (JSON or multi-part form)

Parameter Function

Output (JSON)

Parameter Function
userPref return the player configuration { "userPref":[{"value":"", "value";""},{...}...] }

POST task/reboot

reboot player immediately

Input (JSON or multi-part form)

Parameter Function

Output (JSON)

Parameter Function
null null

POST app/settings/com.iadea.console/new

Add time server configuration

Input (JSON)

Parameter Function
settings new setting object ex. {"settings": [ {"name": "autoTimeServer", "default": "ntp://host{:port}" } ] } 
 "name" : must be autoTimeServer

 "default" : default | ntp://host{:port} 
             set to default player synchronize time with pool.ntp.org, otherwise synchronize with specified ntp host

Output (JSON)

Parameter Function
value return the default value configured above
name return name

POST app/settings/com.iadea.console/update

Update time server configuration

Input (JSON)

Parameter Function
settings new setting object ex. {"settings": [ {"name": "autoTimeServer", "value": "ntp://host{:port}" } ] } 
 "name" : must be autoTimeServer

 "value" : default | ntp://host{:port} 
           set to default player synchronize time with pool.ntp.org, otherwise synchronize with specified ntp host

Output (JSON)

Parameter Function
value return the default value configured above
name return name

POST security/users/admin

Update device password

Input (JSON)

Parameter Function
password string

Output (JSON)

Parameter Function
name return admin by default

System Information

GET system/firmwareInfo

Get firmware version information

Input (JSON or multi-part form)

Parameter Function

Output (JSON)

Parameter Function
firmware version Device firmware version information
family Product model family , such as "AML8726M3-ADAPI"

GET system/modelInfo

Get player model name and other manufacture use only information

Input (JSON or multi-part form)

Parameter Function

Output (JSON)

Parameter Function
modelName Device model name

GET /v2/android.net.wifi.WifiManager/isWifiEnabled

Get Wi-Fi enable/disable information

Input (JSON or multi-part form)

Parameter Function

Output true/false

GET /v2/android.net.wifi.WifiManager/getConnectionInfo

Get Wi-Fi information

Input (JSON or multi-part form)

Parameter Function

Output (JSON)

Parameter Function
BSSID BSSID
detailedState Detailed State
hiddenSSID Whether SSID is hidden
ipAddress IP Address
linkSpeed Link Speed
macAddress MAC Address
networkId Network ID
rssi RSSI info
SSID SSID
supplicantState Supplicant State
Retrieved from "https://www.a-smil.org/index.php?title=REST_Push_API&oldid=520"