Skip to content

Added events to the MCP and Robot #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jan 3, 2015
Merged

Added events to the MCP and Robot #3

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
168ae83
Added events to the robot and MCP
lorenwest Dec 11, 2014
c86e1e7
Added events to the robot and MCP
lorenwest Dec 11, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
142 changes: 102 additions & 40 deletions specification.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ If a requested type is not possible to serve, the API should respond with a 406

## Command Casing

Command names should be snake_cased at all times, both when serialized to be sent down to the client, or when received in a URL.
Command and event names should be snake_cased at all times, both when serialized to be sent down to the client, or when received in a URL.

e.g.

Expand Down Expand Up @@ -109,7 +109,7 @@ Routes will be described below, in a format similar to the following:
Returns an object containing info on the MCP. The MCP response should contain:

- an array of the robots
- an array of commands the MCP supports (represented as strings)
- an array of commands and events the MCP supports (represented as strings)

Example response:

Expand Down Expand Up @@ -137,18 +137,21 @@ Example response:
"driver": "Ping",
"connection": "loopback",
"commands": ["ping"],
"events": ["ping"],
Copy link
Contributor Author

@lorenwest lorenwest Dec 11, 2014

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

At first I named this event "pinged" to reduce command/event name confusion, but changed it to "ping" because that's the name of the event in implementations.

Copy link
Contributor Author

@lorenwest lorenwest Dec 12, 2014

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It appears in cylon.js the command execution pattern is to issue events for results vs. calling callbacks, which is probably why ping is both a command and an event. MCP implementations could choose to auto-expose these command events in the events array, or require them to be explicitly defined.

"details": {
"pin": "13",
"test": "abc"
}
}
],

"commands": [ "hello" ]
"commands": [ "hello" ],
"events": ["test_passed", "test_failed"]
}
],

"commands": [ "echo" ]
"commands": [ "echo" ],
"events": [ "robot_added", "robot_removed" ]
}
}

Expand All @@ -163,6 +166,17 @@ Example response:
"commands": [ "echo" ]
}

### GET /api/events

Returns an array with the specified MCP’s events in string format.

Example response:

// GET /api/events
{
"events": [ "robot_added", "robot_removed" ]
}

### POST /api/commands/:command

Executes the requested command on the MCP.
Expand All @@ -178,6 +192,18 @@ Example response:
"result": 10
}

### GET /api/events/:event

Opens a Server-Sent Events stream that hooks into the provided Event on the MCP.
When the MCP emits the event, the data emitted with the event is sent down the wire to the client.

Example response:

// GET /api/events/robot_removed
data: {
"name": "TempBot"
}

### GET /api/robots

Returns an array of all Robots the server knows about.
Expand Down Expand Up @@ -213,14 +239,16 @@ Example response:
"driver": "Ping",
"connection": "loopback",
"commands": ["ping"],
"events": ["ping"],
"details": {
"pin": "13",
"test": "abc"
}
}
],

"commands": [ "hello" ]
"commands": [ "hello" ],
"events": ["test_passed", "test_failed"]
}
]
}
Expand All @@ -238,35 +266,35 @@ Example response:

// GET /api/robots/TestBot
{
"robot": {
"name": "TestBot",
"name": "TestBot",

"connections": [
{
"name": "loopback",
"adaptor": "Loopback",
"details": {
"port": "/dev/null",
"test": "abc"
}
"connections": [
{
"name": "loopback",
"adaptor": "Loopback",
"details": {
"port": "/dev/null",
"test": "abc"
}
],
}
],

"devices": [
{
"name": "ping",
"driver": "Ping",
"connection": "loopback",
"commands": ["ping"],
"details": {
"pin": "13",
"test": "abc"
}
"devices": [
{
"name": "ping",
"driver": "Ping",
"connection": "loopback",
"commands": ["ping"],
"events": ["ping"],
"details": {
"pin": "13",
"test": "abc"
}
],
}
],

"commands": [ "hello" ]
}
"commands": [ "hello" ],
"events": ["test_passed", "test_failed"]
}

### GET /api/robots/:robot/commands
Expand All @@ -280,6 +308,17 @@ Example response:
"commands": [ "hello" ]
}

### GET /api/robots/:robot/events

Returns an array with the specified Robot’s events in string format.

Example response:

// GET /api/robots/TestBot/events
{
"events": [ "test_passed", "test_failed" ]
}

### POST /api/robots/:robot/commands/:command

Executes the requested command on the robot.
Expand All @@ -294,6 +333,16 @@ Example response:
“result”: “Hello, world”
}

### GET /api/robots/:robot/events/:event

Opens a Server-Sent Events stream that hooks into the provided Event on the robot.
When the MCP emits the event, the data emitted with the event is sent down the wire to the client.

Example response:

// GET /api/robots/TestBot/events/test_passed
data: 8 tests complete (4ms)

### GET /api/robots/:robot/devices

Returns an array containing information about the specified Robot’s Devices.
Expand All @@ -308,6 +357,7 @@ Example response:
"driver": "Ping",
"connection": "loopback",
"commands": ["ping"],
"events": ["ping"],
"details": {
"pin": "13",
"test": "abc"
Expand All @@ -329,34 +379,34 @@ Example response:
"driver": "Ping",
"connection": "loopback",
"commands": [ "ping" ],
"events": ["ping"],
"details": {
"pin": "13",
"test": "abc"
}
}
}

### GET /api/robots/:robot/devices/:device/events/:event
### GET /api/robots/:robot/devices/:device/commands

Opens a Server-Sent Events stream that hooks into the provided Event on the specified device.
When the device emits the event, the data emitted with the event is sent down the wire to the client.
Returns an array of commands the specified Device has.

Example response:

// GET /api/robots/TestBot/devices/ping/events/ping
data: ping

data: ping
// GET /api/robots/TestBot/devices/ping/commands
{
"commands": [ "ping" ]
}

### GET /api/robots/:robot/devices/:device/commands
### GET /api/robots/:robot/devices/:device/events

Returns an array of commands the specified Device has.
Returns an array with the specified Device’s events in string format.

Example response:

// GET /api/robots/TestBot/devices/ping/commands
// GET /api/robots/TestBot/devices/ping/events
{
"commands": [ "ping" ]
"events": [ "ping" ]
}

### POST /api/robots/:robot/devices/:devices/commands/:command
Expand All @@ -373,6 +423,18 @@ Example response:
“result”: "pong"
}

### GET /api/robots/:robot/devices/:device/events/:event

Opens a Server-Sent Events stream that hooks into the provided Event on the specified device.
When the device emits the event, the data emitted with the event is sent down the wire to the client.

Example response:

// GET /api/robots/TestBot/devices/ping/events/ping
data: ping

data: ping

### GET /api/robots/:robot/connections

Returns an array containing information about the specified Robot’s Connections.
Expand Down