Pedal PI - WebService - API documentation
API Endpoint
http://pedalpi.local:3000/v1Pedal Pi - WebService is a Pedal Pi component that offers a Pedal Pi management over REST + WebSocket. This documentation describes the REST API.
-Authentication ¶
Authentication has two purposes: Control access and obtaining token request identifier
-Control access ¶
Not implemented
-Token identifier ¶
With a token identifier, it is possible to send changes if they are identified, so that no notifications of their own changes to WebSocket occur.
-When a connection is established with http://pedalpi.local/ws, a TOKEN message ("type": "TOKEN") returns a uuid4 for the client.
Pedal PI - WebService - API documentation
API Endpoint
http://pedalpi.local:3000/v1Pedal Pi - WebService is a Pedal Pi component that offers a Pedal Pi management over REST + WebSocket. This documentation describes the REST API.
+Authentication ¶
To access API methods, you must be authenticated. The authenticatetion is based on JWT technology.
+Control access ¶
Headers
Content-Type: application/json; charset=UTF-8Body
{
+ "username": "pedal pi",
+ "password": "pedal pi",
+}Headers
Content-Type: application/json; charset=UTF-8Body
{
+ "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MjE5ODM1NDZ9.MKT1XRgqa68ADIdH1ro0MkIWwh9mXrNPjz5q5aUhFKc"
+}Headers
Content-Type: application/json; charset=UTF-8Body
{
+ "error": "Invalid username or password"
+}AuthenticatePOST/auth
For auth, send the username and the password as a json object. In this
+current version, exists only a username: pedal pi
{
- "value": "{token uuid4}",
- "type": "TOKEN"
-}It’s necessary that all requests add the following header parameter.
-x-xsrf-token: {token uuid4}Headers
Content-Type: application/json; charset=UTF-8
x-xsrf-token: {token uuid4}Headers
Content-Type: application/json; charset=UTF-8Body
anythingExample requestGET/ws
It’s a example request for a random address
+ "username": "pedal pi", + "password": "pedal pi", +} +The initial password is pedal pi. ~Please, on the first login, change
+the password~ (in development)!
If the data is correct, will be returned the auth token. +You need send it in every request. See a example in the next section.
+The token has a expiration of 7 days from login response time. If the token has +expired, is necessary request auth to obtains a new token.
+How to use auth token ¶
In the requests, is necessary send the auth token in the header with the following stard:
+Authorization: bearer <token>Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MjE5ODM1NDZ9.MKT1XRgqa68ADIdH1ro0MkIWwh9mXrNPjz5q5aUhFKcHeaders
Content-Type: application/json; charset=UTF-8Body
somethingHeaders
Content-Type: application/json; charset=UTF-8Headers
Content-Type: application/json; charset=UTF-8Body
{
+ "error": "Missing authorization"
+}Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer something eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MjE5ODM1NDZ9.MKT1XRgqa68ADIdH1ro0MkIWwh9mXrNPjz5q5aUhFKcHeaders
Content-Type: application/json; charset=UTF-8Body
{
+ "error": "Invalid header authorization. The Authorization header not match with the standard `Authorization: bearer <token>`"
+}Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MjE5ODM1NDZ9.MKT1XRgqa68ADIdH1ro0MkIWwh9mXrNPjz5q5aUhFKcHeaders
Content-Type: application/json; charset=UTF-8Body
{
+ "error": "Signature verification failed"
+}Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MjE5ODM1NDZ9.MKT1XRgqa68ADIdH1ro0MkIWwh9mXrNPjz5q5aUhFKcHeaders
Content-Type: application/json; charset=UTF-8Body
{
+ "error": "Signature has expired"
+}Example requestGET/something
The Authorization code error is 401.
See the possible errors in right selecting a request.
+Plugins management ¶
It’s possible obtains the Lv2Plugins data in a json format. Pedal Pi uses lilvlib for parse to json.
-Plugins ¶
Headers
Content-Type: application/json; charset=UTF-8Body
{
+Plugins ¶
Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Headers
Content-Type: application/json; charset=UTF-8Body
{
"plugins": [
/* Plugins list */
{"presets": [], ...},
]
-}Plugins listGET/plugins
Get all audio plugins installed
-Reload plugins ¶
Headers
Content-Type: application/json; charset=UTF-8Body
{
+}Plugins listGET/plugins
Get all audio plugins installed
+Reload plugins ¶
Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Headers
Content-Type: application/json; charset=UTF-8Body
{
"status": "ok"
}Headers
Content-Type: application/json; charset=UTF-8Body
{
"error": "lilv not configured"
-}Reload pluginsPUT/plugins/reload
Reloads the lv2 plugins data.
+}Reload pluginsPUT/plugins/reload
Reloads the lv2 plugins data.
To get the audio plugin metadata, you need to install lilv. Check the Lv2EffectBuilder.lv2_plugins_data() method documentation for more details on how to install.
If lilv is not installed, an error (400) is returned.
Plugin ¶
Headers
Content-Type: application/json; charset=UTF-8Body
{
+Plugin ¶
Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Headers
Content-Type: application/json; charset=UTF-8Body
{
"label": "Calf Mono Input",
"microVersion": 0,
"bundles": [],
@@ -481,26 +508,30 @@
"brand": "Calf"
}Schema
Not definedHeaders
Content-Type: application/json; charset=UTF-8Body
{
"error": "Plugin \"https://github.com/ninodewit/SHIRO-Plugins/plugins/larynx\" not installed"
-}Plugin dataGET/plugin/{uri}
Get a specific audio plugin json by uri identifier.
Plugin dataGET/plugin/{uri}
Get a specific audio plugin json by uri identifier.
Some audio plugins have their uri containing #. To get the plugin data,
you need to replace # with %23.
Example:
-Replace
+-
+
- Replace +
plugin/http://guitarix.sourceforge.net/plugins/gx_redeye#chumpwith
+-
+
- with +
plugin/http://guitarix.sourceforge.net/plugins/gx_redeye%23chump- uri
string(required) Example: http://calf.sourceforge.net/plugins/MonoInputThe plugin URI
Banks management ¶
Manages the banks data.
-Banks ¶
Headers
Content-Type: application/json; charset=UTF-8Body
{
+Banks ¶
Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Headers
Content-Type: application/json; charset=UTF-8Body
{
"banks": {
"0": {"index": 0, ...},
"1": {"index": 0, ...}
}
-}List banksGET/banks
Get all banks
+}List banksGET/banks
Get all banks
Bank management ¶
Bank ¶
Manages a bank: creates a new, update, get the bank data or removes it.
-Headers
Content-Type: application/json; charset=UTF-8Body
{
+Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Body
{
"index": -1,
"name": "My new bank",
"pedalboards": [
@@ -518,12 +549,13 @@
It’s necessary updates the (client) bank data with the returned index.
-Manages a bank by index ¶
Headers
Content-Type: application/json; charset=UTF-8Body
{
+Manages a bank by index ¶
Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Headers
Content-Type: application/json; charset=UTF-8Body
{
"index": 1,
"pedalboards": [
{
"connections": [
{
+ "type": "audio",
"input": {
"index": 0,
"effect": 0,
@@ -535,6 +567,7 @@
}
},
{
+ "type": "audio",
"input": {
"index": 0,
"symbol": "playback_1"
@@ -605,10 +638,10 @@
],
"name": "My awesome bank"
}Headers
Content-Type: application/json; charset=UTF-8Body
{
- "error": "Invalid index"
-}Get by indexGET/bank/{bank_index}
Request a bank data with the bank index.
+ "error": "list index out of range" +}Get by indexGET/bank/{bank_index}
Request a bank data with the bank index.
- bank_index
number(required) Example: 1Bank index
-
Headers
Content-Type: application/json; charset=UTF-8Body
{
+Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Body
{
"index": -1,
"name": "My new bank",
"pedalboards": [
@@ -620,15 +653,15 @@
}
]
}Headers
Content-Type: application/json; charset=UTF-8Headers
Content-Type: application/json; charset=UTF-8Body
{
- "error": "Invalid index"
+ "error": "list index out of range"
}Update by indexPUT/bank/{bank_index}
Update a bank
- bank_index
number(required) Example: 1Bank index
-
Headers
Content-Type: application/json; charset=UTF-8Body
{
- "error": "Invalid index"
-}Delete by indexDELETE/bank/{bank_index}
Delete a bank
+Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Headers
Content-Type: application/json; charset=UTF-8Body
{
+ "error": "list index out of range"
+}Delete by indexDELETE/bank/{bank_index}
Delete a bank
- bank_index
number(required) Example: 1Bank index
Pedalboard management ¶
Manages a pedalboard: creates a new, update, get the pedalboard data or removes it.
-Pedalboard ¶
Headers
Content-Type: application/json; charset=UTF-8Body
{
+Pedalboard ¶
Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Body
{
"name": "My new pedalboard",
"effects": [],
"connections": [],
@@ -641,29 +674,29 @@
The pedalboard does not have an identifier, the returned index is only for listing and sorting purpose.
- bank_index
number(required) Example: 1Bank index
-
Manages a pedalboard by index position ¶
Headers
Content-Type: application/json; charset=UTF-8Body
{
+Manages a pedalboard by index position ¶
Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Headers
Content-Type: application/json; charset=UTF-8Body
{
"name": "My new pedalboard",
"effects": [],
"connections": [],
"data": {}
}Headers
Content-Type: application/json; charset=UTF-8Body
{
- "error": "Invalid index"
-}Get by index positionGET/bank/{bank_index}/pedalboard/{pedalboard_index}
Request a pedalboard data with the your index (pedalboard position in bank pedalboards list).
+ "error": "list index out of range" +}Get by index positionGET/bank/{bank_index}/pedalboard/{pedalboard_index}
Request a pedalboard data with the your index (pedalboard position in bank pedalboards list).
- bank_index
number(required) Example: 1Bank index
- pedalboard_index
number(required) Example: 3Pedalboard position in bank pedalboards list
-
Headers
Content-Type: application/json; charset=UTF-8Body
{
+Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Body
{
"name": "My new pedalboard",
"effects": [],
"connections": [],
"data": {}
}Headers
Content-Type: application/json; charset=UTF-8Body
{
- "error": "Invalid index"
+ "error": "list index out of range"
}Update by index positionPUT/bank/{bank_index}/pedalboard/{pedalboard_index}
Update a pedalboard
- bank_index
number(required) Example: 1Bank index
- pedalboard_index
number(required) Example: 3Pedalboard position in bank pedalboards list
-
Headers
Content-Type: application/json; charset=UTF-8Body
{
- "error": "Invalid index"
-}Delete by index positionDELETE/bank/{bank_index}/pedalboard/{pedalboard_index}
Delete a pedalboard
+Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Headers
Content-Type: application/json; charset=UTF-8Body
{
+ "error": "list index out of range"
+}Delete by index positionDELETE/bank/{bank_index}/pedalboard/{pedalboard_index}
Delete a pedalboard
- bank_index
number(required) Example: 1Bank index
- pedalboard_index
number(required) Example: 3Pedalboard position in bank pedalboards list
Pedalboard Data management ¶
Manages a custom data for a specified pedalboard.
@@ -692,14 +725,14 @@ } } } -Manages by key ¶
Headers
Content-Type: application/json; charset=UTF-8Headers
Content-Type: application/json; charset=UTF-8Body
{
+Manages by key ¶
Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Headers
Content-Type: application/json; charset=UTF-8Body
{
"effectPositions": [
{
"x": 159.74801635742188,
"y": 91.4995002746582
}
]
-}Headers
Content-Type: application/json; charset=UTF-8Headers
Content-Type: application/json; charset=UTF-8Body
{}Get by keyGET/bank/{bank_index}/pedalboard/{pedalboard_index}/data/{key}
Request a param data with the your position
+}Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Headers
Content-Type: application/json; charset=UTF-8Body
{}Get by keyGET/bank/{bank_index}/pedalboard/{pedalboard_index}/data/{key}
Request a param data with the your position
If the request with a key that not data has been not persisted yet, the response returns a empty json object:
{}- bank_index
number(required) Example: 1Bank index
- pedalboard_index
number(required) Example: 3Pedalboard position in bank pedalboards list
- key
string(required) Example: pedalpi-apkKey identifier for data
-
Headers
Content-Type: application/json; charset=UTF-8Body
{
+Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Body
{
"effectPositions": [
{
"x": 159.74801635742188,
@@ -725,7 +758,7 @@
For update effect data, view current toggle status effect and update param data.
-Effect data ¶
Headers
Content-Type: application/json; charset=UTF-8Body
{
+Effect data ¶
Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Body
{
"active": true,
"params": [
{
@@ -775,7 +808,7 @@
- bank_index
number(required) Example: 1Bank index
- pedalboard_index
number(required) Example: 3Pedalboard index (position)
-
Manages a effect by index position ¶
Headers
Content-Type: application/json; charset=UTF-8Body
{
+Manages a effect by index position ¶
Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Headers
Content-Type: application/json; charset=UTF-8Body
{
"active": true,
"params": [
{
@@ -817,14 +850,14 @@
"plugin": "http://drobilla.net/plugins/fomp/cs_chorus1",
"technology": "lv2"
}Headers
Content-Type: application/json; charset=UTF-8Body
{
- "error": "Invalid index"
-}Get by index positionGET/bank/{bank_index}/pedalboard/{pedalboard_index}/effect/{effect_index}
Request a effect data with the your index (effect position in pedalboard effects list).
+ "error": "list index out of range" +}Get by index positionGET/bank/{bank_index}/pedalboard/{pedalboard_index}/effect/{effect_index}
Request a effect data with the your index (effect position in pedalboard effects list).
- bank_index
number(required) Example: 1Bank index
- pedalboard_index
number(required) Example: 3Pedalboard position in bank pedalboards list
- effect_index
number(required) Example: 2Effect position in pedalboard effects list
-
Headers
Content-Type: application/json; charset=UTF-8Body
{
- "error": "Invalid index"
-}Delete by index positionDELETE/bank/{bank_index}/pedalboard/{pedalboard_index}/effect/{effect_index}
Delete a effect
+Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Headers
Content-Type: application/json; charset=UTF-8Body
{
+ "error": "list index out of range"
+}Delete by index positionDELETE/bank/{bank_index}/pedalboard/{pedalboard_index}/effect/{effect_index}
Delete a effect
- bank_index
number(required) Example: 1Bank index
- pedalboard_index
number(required) Example: 3Pedalboard position in bank pedalboards list
- effect_index
number(required) Example: 2Effect position in pedalboard effects list
@@ -832,28 +865,29 @@
Manages a param by index position ¶
Params contains a index attribute, but the requests needs the index position in params list.
Headers
Content-Type: application/json; charset=UTF-8Body
{
+Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Headers
Content-Type: application/json; charset=UTF-8Body
{
"maximum": 30,
"minimum": 0,
"value": 17,
"symbol": "delay",
"index": 2
}Headers
Content-Type: application/json; charset=UTF-8Body
{
- "error": "Invalid index"
-}Get by index positionGET/bank/{bank_index}/pedalboard/{pedalboard_index}/effect/{effect_index}/param/{param_index}
Request a param data with the your position
+ "error": "list index out of range" +}Get by index positionGET/bank/{bank_index}/pedalboard/{pedalboard_index}/effect/{effect_index}/param/{param_index}
Request a param data with the your position
- bank_index
number(required) Example: 1Bank index
- pedalboard_index
number(required) Example: 3Pedalboard position in bank pedalboards list
- effect_index
number(required) Example: 2Effect position in pedalboard effects list
- param_index
number(required) Example: 0Param position in effect params list
-
Headers
Content-Type: text/plainBody
1.1901190476159431Headers
Content-Type: application/json; charset=UTF-8Body
{
- "error": "Invalid index"
+Headers
Content-Type: text/plain
Authorization: bearer <auth token>Body
1.1901190476159431Headers
Content-Type: application/json; charset=UTF-8Body
{
+ "error": "list index out of range"
}Update by index positionPUT/bank/{bank_index}/pedalboard/{pedalboard_index}/effect/{effect_index}/param/{param_index}
Update a pedalboard
- bank_index
number(required) Example: 1Bank index
- pedalboard_index
number(required) Example: 3Pedalboard position in bank pedalboards list
- effect_index
number(required) Example: 2Effect position in pedalboard effects list
- param_index
number(required) Example: 0Param position in effect params list
Effect connections management ¶
Connect and disconnect effects.
-Manages by key ¶
Headers
Content-Type: application/json; charset=UTF-8Body
{
+Manages by key ¶
Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Body
{
+ "type": "audio",
"output": {
"effect": 0,
"symbol": "out",
@@ -863,7 +897,8 @@
"symbol": "playback_2",
"index": 1
}
-}Headers
Content-Type: application/json; charset=UTF-8Body
{
+}Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Body
{
+ "type": "audio",
"output": {
"effect": 0,
"symbol": "out",
@@ -877,7 +912,7 @@
}Add a new connectionPOST/bank/{bank_index}/pedalboard/{pedalboard_index}/connect
Add a new connection between pedalboards
- bank_index
number(required) Example: 1Bank index
- pedalboard_index
number(required) Example: 3Pedalboard position in bank pedalboards list
-
Headers
Content-Type: application/json; charset=UTF-8Body
{
+Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Body
{
"output": {
"effect": 0,
"symbol": "out",
@@ -887,7 +922,7 @@
"symbol": "playback_2",
"index": 1
}
-}Headers
Content-Type: application/json; charset=UTF-8Body
{
+}Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Body
{
"output": {
"effect": 0,
"symbol": "out",
@@ -905,11 +940,11 @@
URI Parameters- bank_index
number (required) Example: 1Bank index
- pedalboard_index
number (required) Example: 3Pedalboard position in bank pedalboards list
Current management ¶
Provides easy access to current pedalboard settings
-Retrieve current ¶
Headers
Content-Type: application/json; charset=UTF-8Body
{
+Retrieve current ¶
Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Headers
Content-Type: application/json; charset=UTF-8Body
{
"bank": 1,
"pedalboard": 0
-}Current indexGET/current
Returns the current pedalboard index and your bank index.
-Manages the current effect ¶
Headers
Content-Type: application/json; charset=UTF-8Body
{
+}Current indexGET/current
Returns the current pedalboard index and your bank index.
+Current bank data ¶
Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Headers
Content-Type: application/json; charset=UTF-8Body
{
"bank": {
"index": 2,
"name": "Rock 80's",
@@ -923,55 +958,67 @@
]
},
"pedalboard": 0
-}Current dataGET/current/data
Returns the json data of the bank of the current pedalboard.
-Manages the current pedalboard ¶
Headers
Content-Type: application/json; charset=UTF-8Set current pedalboardPUT/current/bank/{bank_index}/pedalboard/{pedalboard_index}
The the specified pedalboard for the current. The audio processing will be setted for the pedalboard configuration (adding effects and your relationships).
+}Current dataGET/current/data
Returns the json data of the bank of the current pedalboard.
+Manages current pedalboard ¶
Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Headers
Content-Type: application/json; charset=UTF-8Set current pedalboardPUT/current/bank/{bank_index}/pedalboard/{pedalboard_index}
Define the current pedalboard based on the specified URI. The audio processing +will be setted for the pedalboard configuration.
- bank_index
number(required) Example: 1Bank index
- pedalboard_index
number(required) Example: 3Pedalboard position in bank pedalboards list
-
Maneges effect status of the current pedalboard ¶
Headers
Content-Type: application/json; charset=UTF-8Toggle effect statusPUT/current/effect/{effect_index}
Toggle the status of a effect of the current pedalboard.
+Maneges effect status of the current pedalboard ¶
Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Headers
Content-Type: application/json; charset=UTF-8Toggle effect statusPUT/current/effect/{effect_index}
Toggle the status of a effect of the current pedalboard.
Toggle status effect: Changes the status active → bypass or the reverse (bypass → active) for a effect loaded.
- effect_index
number(required) Example: 2Effect position in pedalboard effects list
Move ¶
Move Bank ¶
Use it to changes the order of the banks in banks list.
-Headers
Content-Type: application/json; charset=UTF-8Headers
Content-Type: application/json; charset=UTF-8Change banks orderPUT/move/bank/{from_index}/to/{to_index}
Change the position of a bank in banks list
+Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Headers
Content-Type: application/json; charset=UTF-8Change banks orderPUT/move/bank/{from_index}/to/{to_index}
Change the position of a bank in banks list
- from_index
number(required) Example: 3Actual bank position in banks list
- to_index
number(required) Example: 2New bank position in banks list
Move Pedalboard ¶
Use it to changes the order of the pedalboards of a bank.
-Headers
Content-Type: application/json; charset=UTF-8Headers
Content-Type: application/json; charset=UTF-8Change order of a pedalboard in your bankPUT/move/bank/{bank_index}/pedalboard/{from_index}/to/{to_index}
Change the position of a pedalboard in your bank
+Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Headers
Content-Type: application/json; charset=UTF-8Change order of a pedalboard in your bankPUT/move/bank/{bank_index}/pedalboard/{from_index}/to/{to_index}
Change the position of a pedalboard in your bank
- bank_index
number(required) Example: 1Index of Bank that contains the pedalboard
- from_index
number(required) Example: 3Actual pedalboard position in bank pedalboards list
- to_index
number(required) Example: 2New pedalboard position in bank pedalboards list
Configurations ¶
Manages Pedal Pi configurations
-Device Name ¶
Headers
Content-Type: application/json; charset=UTF-8Get device name (zeroconf)GET/configurations/device_name
Get the device name that will appear in a search performed by zeroconf.
-Set Device Name ¶
Headers
Content-Type: application/json; charset=UTF-8Set the device name (zeroconf)PUT/configurations/device_name/{new_name}
Change the device name that will appear in a search performed by zeroconf.
+Device Name ¶
Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Body
{
+ "name": "RaspberryPi"
+}Get device name (zeroconf)GET/configurations/device_name
Get the device name that will appear in a search performed by zeroconf.
+Set Device Name ¶
Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Set the device name (zeroconf)PUT/configurations/device_name/{new_name}
Change the device name that will appear in a search performed by zeroconf.
- new_name
string(required) Example: Paulo - Pedal PiNew device name
-
Component data ¶
In addition to the possibility of persisting additional data for a particular pedalboard, it is possible to persist isolated data, that is, they do not share the same storage space with pedalboards.
+Component data ¶
In addition to the possibility of persisting additional data for a specific pedalboard, it’s possible to persist isolated data, that is, they do not share the same storage space with pedalboards.
Manage data ¶
Access to the data is through a key. This key must be unique: more than one component using the same key will result in the same storage space for both.
It is expected, although not mandatory, that data from a component using this API have a unique key.
-Headers
Content-Type: application/json; charset=UTF-8Body
{
+Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Body
{
"a key": "a value"
-}Headers
Content-Type: application/json; charset=UTF-8Body
{}Get component dataGET/data/{key}
Get the current data persisted for the informed key. If any data has previously persisted, returns a empty dict ({}).
Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Body
{}Get component dataGET/data/{key}
Get the current data persisted for the informed key. If any data has previously persisted, returns a empty dict ({}).
- key
string(required) Example: MyAwesomeComponentData component identifier. In format
-[a-zA-Z-0-9]+
Headers
Content-Type: application/json; charset=UTF-8Body
{"current-data": {"name": "test"}, {"value": [1, 2, 3]}}Set component dataPUT/data/{key}
Persists a data for the informed key.
Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Body
{"current-data": {"name": "test"}, {"value": [1, 2, 3]}}Set component dataPUT/data/{key}
Persists a data for the informed key.
All current content is replaced by new.
When adding a new data, remember to stick with what has already been persisted.
- key
string(required) Example: MyAwesomeComponentData component identifier. In format
-[a-zA-Z-0-9]+
Headers
Content-Type: application/json; charset=UTF-8Clear component dataDELETE/data/{key}
Removes the current data persisted for the informed key.
Headers
Content-Type: application/json; charset=UTF-8
Authorization: bearer <auth token>Clear component dataDELETE/data/{key}
Removes the current data persisted for the informed key.
Be cautious and do not erase data from other components that you are not managing.
- key
string(required) Example: MyAwesomeComponentData component identifier. In format
[a-zA-Z-0-9]+
WebSocket ¶
Pedal Pi - WebService uses WebSockets to receive notification of changes made by other clients. For example, consider a Pedal Pi configured with the Raspberry-P0 and WebSocket components, when the user presses a button to change the current pedalboard, WebService clients will be notified that the status of the application has changed via their WebSocket connections.
-In order for a client to not receive notifications of state changes made by the client itself, TOKEN identifier must be passed in the header.
+Register client ¶
After the connection is stabilised, is necessary request the self register using +the auth token. Send to server:
+{
+ "register": "<token>"
+}After the sucessful registration, the client will be receive notifications. +In the next section they will be presented.
+After the auth token expires, when occurs any update, will be sent to the client +a message error instead the data:
+{"error": "Token has been expired. Your data now is possibly unsynchronized"}WebSocket notification messages
Notification messages have a type field that determines the type of notification. EFFECT-TOGGLE, for example, informs that the notification refers to changing the current state of an effect (whether it is active or not).
Some message types have an updateType field to tell you what type of update occurred. The accepted values for updateType are CREATED, UPDATED and DELETED. A type=CONNECTION message with updateType=DELETED indicates that a connection (which is described in the other fields of the message) has been removed.
For implementation details, check updates_observer_socket.py.
For implementation details, check websocket_connection_observer.py.
Notification on_current_pedalboard_changed
-
@@ -1081,6 +1128,7 @@
Notification on_current_pedalboard_changedname":"hehueuhes ea",
"connections":[
{
+ "type": "audio",
"input":{
"effect":0,
"symbol":"in_l",
@@ -1092,6 +1140,7 @@ Notification on_current_pedalboard_changed}
},
{
+ "type": "audio",
"input":{
"symbol":"playback_1",
"index":0
@@ -1124,8 +1173,9 @@ Notification on_bank_updated type
":"BANK",
"updateType":"DELETED",
"bank":3,
- "value":{
+ "value": {
"name":"My bank",
+ "index":3,
"pedalboards":[
{
"data":{
@@ -1137,6 +1187,7 @@ Notification on_bank_updated name
":"Empty pedalboard",
"connections":[
{
+ "type": "audio",
"input":{
"symbol":"playback_1",
"index":0
@@ -1148,8 +1199,7 @@ Notification on_bank_updated }
]
}
- ],
- "index":3
+ ]
}
}
@@ -1187,6 +1237,7 @@ Notification on_pedalboard_updated
"name":"Guitar hero",
"connections":[
{
+ "type": "audio",
"input":{
"symbol":"playback_1",
"index":0
@@ -1594,6 +1645,7 @@ Notification on_connection_updated
"bank":2,
"pedalboard":0,
"value":{
+ "type": "audio",
"input":{
"effect":3,
"symbol":"in1",
@@ -1615,6 +1667,7 @@ Notification on_connection_updated
"bank":2,
"pedalboard":0,
"value":{
+ "type": "audio",
"input":{
"effect":2,
"symbol":"in_l",
@@ -1628,7 +1681,7 @@ Notification on_connection_updated
}
Notification on_current_pedalboard_changed}
},
{
+ "type": "audio",
"input":{
"symbol":"playback_1",
"index":0
@@ -1124,8 +1173,9 @@ Notification on_bank_updated type
":"BANK",
"updateType":"DELETED",
"bank":3,
- "value":{
+ "value": {
"name":"My bank",
+ "index":3,
"pedalboards":[
{
"data":{
@@ -1137,6 +1187,7 @@ Notification on_bank_updated name
":"Empty pedalboard",
"connections":[
{
+ "type": "audio",
"input":{
"symbol":"playback_1",
"index":0
@@ -1148,8 +1199,7 @@ Notification on_bank_updated }
]
}
- ],
- "index":3
+ ]
}
}on_pedalboard_updated
"name":"Guitar hero",
"connections":[
{
+ "type": "audio",
"input":{
"symbol":"playback_1",
"index":0
@@ -1594,6 +1645,7 @@ Notification on_connection_updated
"bank":2,
"pedalboard":0,
"value":{
+ "type": "audio",
"input":{
"effect":3,
"symbol":"in1",
@@ -1615,6 +1667,7 @@ Notification on_connection_updated
"bank":2,
"pedalboard":0,
"value":{
+ "type": "audio",
"input":{
"effect":2,
"symbol":"in_l",
@@ -1628,7 +1681,7 @@ Notification on_connection_updated
}
on_connection_updated
"bank":2,
"pedalboard":0,
"value":{
+ "type": "audio",
"input":{
"effect":2,
"symbol":"in_l",
@@ -1628,7 +1681,7 @@ Notification on_connection_updated
}
Generated by aglio on 28 May 2017