OSC Protocol API

 

The OSC Protocol API is the Google Open Spherical Camera Protocol (OSC Protocol) APIs.

 

NameDescription
/osc/checkForUpdates Updates the fingerprint to reflect the current camera state by comparing it with the fingerprint held by the client.
/osc/commands/execute Executes specified commands on the camera. The output is a command object.
/osc/commands/status Returns the status for previous inProgress commands. 
/osc/info Returns the basic information of the Friends Camera device.
/osc/state Returns the device information that change over time such as battery level, battery state, etc.

Open All


/osc/checkForUpdates
Description

The /osc/checkForUpdates API updates the fingerprint to reflect the current camera state by comparing it with the fingerprint held by the client.

A timeout scheme can be used to periodically check the camera state at intervals of ‘timeout’ seconds. If the client’s fingerprint and the camera’s current fingerprint are equal, the camera waits for ‘timeout’ and returns its response. The camera returns the new fingerprint to the client immediately if the camera’s fingerprint has been changed.

  • The fingerprint algorithm

3 digit(batteryLevel)

1 digit(batteryStatus) - 0: discharging, 1: charging(USB), 2: charging(AC), 3: charged

1 char(fileChanged) - X: not changed, A: file added, D: file deleted

1 digit(SD card status) - 0: unmount, 1: mount

2 digit(Capture status) - 0 : idle / 01 : recording / 02 : shooting / 03 : timer_counting / 04 : recording_no_preview / 05 : idle_by_temperature / 06 : idle_by_network_state / 07 : interval / 09 : burstshot / 10 : max_file_size_reached / 11 : storage_full / 12 : liveStreaming_start_fail / 13 : timelapse / 14 : looping / 15 : recording_by_customkey / 16 : timelapse_by_customkey / 17 : looping_by_customkey / 18 : liveStreaming / 19 : liveStreaming_WithRecording / 20 : liveStreaming_error_delay / 21 : liveStreaming_error_server_reject / -1 : error ( camera open failed.)

1 digit(Camera ID) - 0 : half-front-camera, 1 : half-rear-camera, 2 : full-front-camera, 3 : full-rear-camera

1 digit (Network Type) - 0: noSim, 1: no network, 2: 2G, 3:3G, 4:LTE

1 char(Thermal Sleep) - G: good, O: over heat

1 char(data limit) - N: normal, W: warning, L: limit

3 digit(Extra) - "000"

4 digit(Current time) – current time suffix to make the fingerprint a unique one

Example 0940X1014GN0000182

Syntax

POST /osc/checkForUpdates HTTP/1.1

Input Parameters

Parameter

Data

Type

Description

Required

stateFingerprint

String

The fingerprint held by the client (acquired from /osc/state API)

Required

waitTimeout

Integer

If the fingerprint has not been changed, the camera waits for this timeout seconds and then returns the response.

Optional

 

Output Parameters

Parameter

Data

Type

Description

Required

stateFingerprint

String

The current fingerprint of the camera device

Required

throttleTimeout

Integer

Timeout for the client to wait before making another update call. The server always returns 0 since it operates in a synchronous manner.

Optional

Errors

Error Code

Data

Type

Description

missingParameter

String

stateFingerprint is not specified.

invalidParameterName

String

One or more input parameter names is unrecognized.

invalidParameterValue

String

The parameter names are recognized, but one or more values is invalid; for example, waitTimeout is out of range or its type is incorrect.

serverError

String

The server was unable to determine an appropriate throttleTimeout value for its response. The server problem will be identified by the 5XX value returned in the response. Camera manufacturers should supply a table of 5XX codes and corresponding server states that can throw this error.

Example
Request
POST /osc/checkForUpdates HTTP/1.1
Host: [camera ip address]:[httpUpdatesPort]
Content-Type: application/json;charset=utf-8
Accept: application/jsonContent-Length: {CONTENT_LENGTH}
X-XSRF-Protected: 1
 
{
    "stateFingerprint": "0940X1014GN0000182",
    "waitTimeout": 300
}
 
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Content-Length: {CONTENT_LENGTH}
X-Content-Type-Options: nosniff
 
{
    "stateFingerprint": "0940X1014GN0000182",
    "throttleTimeout": 0
}

/osc/commands/execute
Description

The /osc/commands/execute API executes specified commands on the camera. The output is a command object.

Syntax

POST /osc/commands/execute HTTP/1.1

Host: [camera ip address]:[httpPort]

Content-Type: application/json;charset=utf-8

Accept: application/json

Content-Length: {CONTENT_LENGTH}

X-XSRF-Protected: 1

Input Parameters

Parameter

Data

Type

Description

Required

name

String

The command to be executed.

Required

parameters

Object

Command input parameters according to the command definitions specification. See OSC Commands API section for details.

Required

 

Output Parameters

Return

Value

Data

Type

Description

Required

name

String

The command to be executed.

Required

state

String

State of the command. Should be one of the following: done - Complete, results have been returned in this response. inProgress - Execution is still in progress. error - Failed, see error in the response.

Required

id

String

Command ID. This value is required for commands returning the status inProgress. For example, the camera.takePicture command takes a few seconds due to the need for stitching. See the “Status” section for more details.

Optional

results

Object

Command results. This value is required for commands returning state done if the command is expected to return results; for example, “results” : { “AAA”: “BBB”, ... } Please refer to OSC API Specification for examples.

Optional

error

Object

Command error description. This value is required for commands returning state error; for example, “error”:

{ “code”: “missingParameter” }

Optional

progress

Object

Command progress description. This value is required for commands returning state inProgress; for example, “progress”: { “completion”: 0.8 }

Optional

Errors

Error Code

Data

Type

Description

unknownCommand

String

Requested command is unknown.

cameraInExclusiveUse

String

Camera is already in exclusive use, new session can’t be started.

missingParameter

String

One or more required parameters were not specified.

invalidParameterName

String

One or more input parameter or option name was unrecognized or unsupported.

invalidParameterValue

String

The parameter or option names were recognized, but one or more values is invalid; for example, the value is out of range.

Example
Request
POST /osc/commands/execute HTTP/1.1
Host: [camera ip address]:[httpPort]
Content-Type: application/json;charset=utf-8
Accept: application/json
Content-Length: {CONTENT_LENGTH}
X-XSRF-Protected: 1
 
{
    "name": "camera.setOptions",
    "parameters": {
        "options": {
            "iso": 200,
            "exposureCompensation": -2
        }
    }
}
 
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Content-Length: {CONTENT_LENGTH}
X-Content-Type-Options: nosniff
 
{
    "name": "camera.setOptions",
    "state": "done"
}
Request
POST /osc/commands/execute HTTP/1.1
Host: [camera ip address]:[httpPort]
Content-Type: application/json;charset=utf-8
Accept: application/json
Content-Length: {CONTENT_LENGTH}
X-XSRF-Protected: 1
 
{
    "name": "camera.takePicture",
}
 
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Content-Length: {CONTENT_LENGTH}
X-Content-Type-Options: nosniff
 
{
    "name": "camera.takePicture",
    "state": "inProgress",
    "id": "90ABCD",
    "progress": {
        "completion": 0
    }
}

/osc/commands/status
Description

The /osc/commands/status API returns the status for previous inProgress commands. The status API is useful for polling the progress of a previously issued command; for example, determining whether camera.takePicture has completed.

Syntax

POST /osc/commands/status HTTP/1.1

Parameter

Parameter

Data Type

Description

Required

id

String

Command ID returned by a previous call to /osc/commands/execute

Required

Return Value

The output is also a command object (see Output of /osc/commands/execute)

Exceptions

Error Code

Data

Type

Description

missingParameter

String

The id is not specified. This parameter requires a command ID returned by a previous call to /osc/commands/execute.

invalidParameterName

String

The input parameter is unrecognized.

invalidParameterValue

String

The input parameter is recognized, but its value is invalid; for example, id value doesn't exist or its type is incorrect.

 

Example
Request
POST /osc/commands/status HTTP/1.1
Host: [camera ip address]:[httpPort]
Content-Type: application/json;charset=utf-8
Accept: application/json
Content-Length: {CONTENT_LENGTH}
X-XSRF-Protected: 1
 
{
    "id": "90ABCD"
}
 
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Content-Length: {CONTENT_LENGTH}
X-Content-Type-Options: nosniff
 
{
    "name": "camera.takePicture",
    "state": "done",
    "results": {
        "fileUri": "ABC.JPG"
    }
}

/osc/info
Description

The /osc/info API returns the basic information of the Friends Camera device.

Syntax

GET /osc/info HTTP/1.1

Parameter

This command takes no input.

Return Value

Return Value

Data Type

Description

Required

manufacturer

String

The camera manufacturer.

Not defined

model

String

The camera model.

Not defined

serialNumber

String

Serial number.

Not defined

firmwareVersion

String

Current firmware version.

Not defined

supportUrl

String

URL for the camera’s support webpage.

Not defined

gps

Boolean

True if the the camera has GPS.

Not defined

gyro

Boolean

True if the camera has Gyroscope.

Not defined

uptime

Integer

Number of seconds since the camera boot.

Not defined

api

String Array

List of supported APIs.

Not defined

endpoints*

Object

A JSON object containing information about the camera’s endpoints. See the next table for endpoints Object.

Not defined

apiLevel

String

OSC API level. (Default: “v2”)

Not defined

IMEI

String

IMEI number

Not defined

lineNumber

String

(phone) number

Not defined

MSN

String

Manufacture Serial Number

Not defined

 

* endpoints Object

This JSON object provides information on the ports the camera uses for endpoints.

Return Value

Data Type

Description

Required

httpPort

Integer

Port for HTTP server. (Default: 6624)

Not defined

httpUpdatesPort

Integer

Port to receive updates over HTTP (Default: 6624)

Not defined

Exceptions

This command returns no errors.

Example
Request
GET /osc/info HTTP/1.1
Host: [camera ip address]:[httpPort]
Accept: application/json
X-XSRF-Protected: 1
 
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Content-Length: {CONTENT_LENGTH}
X-Content-Type-Options: nosniff
 
{
    "manufacturer": "LGE",
    "model": "LG-R105",
    "serialNumber": "LGR105cf99f269",
    "firmwareVersion": "R105160302",
    "supportUrl": "developer.lge.com/friends",
    "endpoints": {
        "httpPort": 6624,
        "httpUpdatesPort": 6624
    },
    "gps": true,
    "gyro": true,
    "uptime": 48,
    "apiLevel": "v2",
    "api": [
        "/osc/checkForUpdates",
        "/osc/commands/execute",
        "/osc/commands/status",
        "/osc/info",
        "/osc/state"
     ]
}

/osc/state
Description

The /osc/state API returns the device information that change over time such as battery level, battery state, etc.

Syntax

POST /osc/state HTTP/1.1

Input Parameters

This command takes no input.

Output Parameters

Return Value

Data Type

Description

Required

fingerprint

String

The current fingerprint of the camera device

Not defined

state*

Object

An Object that contains the camera’s current information

Not defined

* state Object

Return Value

Data Type

Description

Required

storageChanged

Boolean

SD card detected: true

SD card not detected: false

Not defined

batteryLevel

Number

Remaining battery level in percentage

Not defined

_chargeState

String

Battery charging state

Not defined

_sdCardState

Boolean

SD card not inserted: "false"

SD card inserted: "true"

Not defined

_fileChanged

String

Most recent file activity

Added: "A", deleted: "D", no change: "X"

Not defined

_captureState

String

Camera’s recording state (String).

See Capture status (2 digits) in fingerprint algorithm of /osc/checkForUpdates.

0 : "idle"

1 : "recording"

2 : "shooting"

3 : "timer_counting"

4 : "recording_no_preview"

5 : "idle_by_temperature"

6 : "idle_by_network_state"

7 : "interval"

9 : "burstshot"

10 : "max_file_size_reached"

11 : "storage_full"

12 : "liveStreaming_start_fail"

13 : "timelapse"

14 : "looping"

15 : "recording_by_customkey"

16 : "timelapse_by_customkey"

17 : "looping_by_customkey"

18 : "liveStreaming"

19 : "liveStreaming_WithRecording"

20 : liveStreaming_error_delay

21 : liveStreaming_error_server_reject

-1 : "error" ( camera open failed.)

Not defined

_cameraId

String

The state of camera lens settings.

full-front-camera,full-rear-camera,half-front-camera,half-rear-camera

Not defined

_networkType

String

Network type (noSim, dataOff, unknown, 2G, 3G, LTE)

Not defined

_signalLevel

Integer

Network signal level (0~4)

Not defined

_wifiLevel

Integer

WiFi signal level (0~3)

Not defined

_connectionType

String

Connection type between the camera and smartphone "softAP", "overAP"

Not defined

_isRoamingConnected

Boolean

Roaming network connection state

Not defined

_smsCount

Integer

The total number of received SMS messages

Not defined

_thermalWarningNoti

Boolean

Indicates overheating on camera device. Returns false when normal.

Not defined

_reachData

String

data usage indicator

“N”: normarl, “W”: warning, “L”: limit

Not defined
Errors

This command returns no errors.

Example
Request
POST /osc/state HTTP/1.1
Host: [camera ip address]:[httpPort]
Accept: application/json
X-XSRF-Protected: 1
 
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Content-Length: {CONTENT_LENGTH}
X-Content-Type-Options: nosniff
 
{
    "fingerprint": "0951X1034G00009021",
    "state": {
        "batteryLevel": 0.95,
        "_chargeState": "charging(USB)",
        "_fileChanged": "X",
        "_sdCardState": true,
        "storageChanged": true,
        "_captureState": "idle",
        "_cameraId": "full-rear-camera",
        "_networkType": "LTE",
        "_signalLevel": 4,
        "_wifiLevel": 0,
        "_connectionType": "softAP",
        "_smsCount": 0,
        "_thermalWarningNoti": false
    }
}

Navigation