Author Topic: Sequencer integration APIs  (Read 1405 times)

Offline keithsw1111

  • Newbie
  • *
  • Join Date: Jun 2015
  • Location:
  • Posts: 26
  • Kudos: 2
Sequencer integration APIs
« on: December 07, 2016, 01:48:37 PM »
I'll take first cut at this ... given xlights has built some sort of integration but I would prefer that we were using published interfaces rather than unpublished and thus potentially brittle integration techniques. So here are some of the API's I would like to see:


1. Upload channel configuration for FPP output via e131
2. Upload songs/fseqs
3. Upload channel configuration for FPP input via e131 (essentially the same as 1 but different purpose)
4. Upload output configuration (for rgb-cape/pi hat etc)
5. Query output configuration (for rgb-cape/pi hat etc)

6/7. as for 4/5 but for USB outputs
8. Restart FFPD
9. Upload model channel configuration ... or maybe this is just a generic upload function ... rather than using FTP which is pretty slow on the pi
10. Query FPP version (so we know which APIs are supported)
11. Backup all or part of the configuration ... in case the user wants to undo an upload ... and the requisite API to actually do the undo

I am sure there are others but this seems a reasonable starting set ... until they are available I guess we will just simulate the current UI calls to achieve the integration. As Sean says our objective should be that users only need to set their configuration once ... and from there upload it everywhere required. Only the truly unique things like P10 panel orientation setup and the like should be only possible to config via the UI.

Offline tjames

  • Moderator
  • *****
  • Join Date: Dec 2014
  • Location: Detroit
  • Posts: 209
  • Kudos: 3
Re: Sequencer integration APIs
« Reply #1 on: December 07, 2016, 02:26:00 PM »
I'll take first cut at this ... given xlights has built some sort of integration but I would prefer that we were using published interfaces rather than unpublished and thus potentially brittle integration techniques. So here are some of the API's I would like to see:


1. Upload channel configuration for FPP output via e131
2. Upload songs/fseqs
3. Upload channel configuration for FPP input via e131 (essentially the same as 1 but different purpose)
4. Upload output configuration (for rgb-cape/pi hat etc)
5. Query output configuration (for rgb-cape/pi hat etc)

6/7. as for 4/5 but for USB outputs
8. Restart FFPD
9. Upload model channel configuration ... or maybe this is just a generic upload function ... rather than using FTP which is pretty slow on the pi
10. Query FPP version (so we know which APIs are supported)
11. Backup all or part of the configuration ... in case the user wants to undo an upload ... and the requisite API to actually do the undo

I am sure there are others but this seems a reasonable starting set ... until they are available I guess we will just simulate the current UI calls to achieve the integration. As Sean says our objective should be that users only need to set their configuration once ... and from there upload it everywhere required. Only the truly unique things like P10 panel orientation setup and the like should be only possible to config via the UI.


Version 2 of FPP will be shipping with a complete JSON REST api with endpoints to control everything. In fact the new v2 UI is entirely API driven, so anything that can be done via the interface, can be done via the API. So in v2, you won't need to upload anything other than songs/sequences (and that is still done via the api), you would just make a http request to whatever endpoint you're querying or sending data to along with your payload and fpp will take care of it.


I have a rough outline of the current endpoints and some of the proposed endpoints as well that I will post as soon as I get a chance to go through and flush out the rest of them so there's a complete list.
- Tim

Online Bshaver

  • Moderator
  • *****
  • Join Date: Aug 2014
  • Location: Denver, CO
  • Posts: 1,230
  • Kudos: 20
Re: Sequencer integration APIs
« Reply #2 on: December 07, 2016, 02:34:27 PM »
Tim,
Is there a branch that i can install or switch to.


I have put in a Debian VM here and I have it running.


I would clone it and use it for the V2 stuff

Offline CaptainMurdoch

  • Administrator
  • *****
  • Join Date: Sep 2013
  • Location: Washington
  • Posts: 7,854
  • Kudos: 139
Re: Sequencer integration APIs
« Reply #3 on: December 07, 2016, 02:59:13 PM »
Tim, what provisions do you have for batch upload/config?

I think having a batch upload/configure would be easiest on external programs.  Rather than having to make 100 API calls to create 100 universes, the client would post/put a piece of JSON which would have all 100 universes defined.  If each entry had an ID number, it would overwrite the existing universe with that ID.
-
Chris

Offline keithsw1111

  • Newbie
  • *
  • Join Date: Jun 2015
  • Location:
  • Posts: 26
  • Kudos: 2
Re: Sequencer integration APIs
« Reply #4 on: December 07, 2016, 03:03:00 PM »
Tim I know there is a new ui in the works and has been for quite some time. I would love to see the draft api because as the captains response shows there may be some differing views on the features the app should offer for the best user experience.

Offline tjames

  • Moderator
  • *****
  • Join Date: Dec 2014
  • Location: Detroit
  • Posts: 209
  • Kudos: 3
Re: Sequencer integration APIs
« Reply #5 on: December 07, 2016, 03:51:10 PM »
Tim, what provisions do you have for batch upload/config?

I think having a batch upload/configure would be easiest on external programs.  Rather than having to make 100 API calls to create 100 universes, the client would post/put a piece of JSON which would have all 100 universes defined.  If each entry had an ID number, it would overwrite the existing universe with that ID.


In general, how the endpoint behaves/how the resource is treated is based on the type of request. In a nutshell, POST/PUT requests replace the resource whereas PATCH requests only replace the data you specify.


In the endpoints that are currently implemented, there's generally an 'index' endpoint that works with an entire resource but there are also child endpoints that provide control for only parts of the resource.


For example, take playlists endpoint:



GET        /playlists                           - Lists all playlists
GET        /playlists/{name}                 - List specified playlist and entries
PUT        /playlists/{name}            - Updates/replaces playlist
PATCH    /playlists/{name}            - Updates specified portion of playlist
DELETE   /playlists/{name}            - Deletes playlist
POST      /playlists/create                    - Creates new playlist
GET        /playlists/{name}/{entry}    - Lists specified entry in specified playlist
PUT        /playlists/{name}/{entry}    - Updates/replaces specified entry in specified playlist
PATCH    /playlists/{name}/{entry}    - Updates portion of specified entry in specified playlist
DELETE   /playlists/{name}/{entry}    - Deletes playlist entry


In most instances, external programs likely wouldn't use the child endpoints, they would simply replace the resource entirely with their new data. I may even remove some of the child endpoints since the UI rarely uses them since everything is managed from a single state tree. So while updates to the UI are/can be granular, saving/writing to disk/db is generally in bulk. Hope that makes sense.


Offline jeffu231

  • Newbie
  • *
  • Join Date: Sep 2014
  • Location:
  • Posts: 2
  • Kudos: 0
Re: Sequencer integration APIs
« Reply #6 on: December 08, 2016, 07:34:16 PM »
I am in favor of the API being restful API's with JSON payloads. This should allow fully cross platform integrations with about anything as it is a pretty common standard.


I agree with the idea that for most things 3rd party consumers should be able to configure most of the common everyday things. FPP becomes more like another controller or device the sequencer interfaces with for those that want to do most of their work in one place. I can envision users configuring everything in their sequencer and then that can just be mirrored into FPP. This includes get/post/update of all the sequence and audio files as well as playlists and output configuration. FPP status information would be a nice to have as well.


Another item I would like to see support for is driving the test type features from the API as well. Once the data gets to FPP, it is just a bunch of raw data mapped to channels. To use the test facilities in FPP you have to know what channels go with something to test it. In V3 we have a very robust web interface for testing that you can turn on actual props you have been working with and not have to think about the channel mapping. I could see this being extended to drive the outputs from the sequencer or switch and drive FPP which then helps confirm that things are mapped and working correctly. The 3rd party UI would need to do the prop to channel translation and then the FPP API could support some form of channel range and color API to command them on/off.



Offline lrhorer

  • Full Member
  • ***
  • Join Date: Feb 2015
  • Location:
  • Posts: 161
  • Kudos: -16
Re: Sequencer integration APIs
« Reply #7 on: January 01, 2017, 04:16:44 PM »
What about lower level (device) functions?  It would be great to have APIs available to handle direct interfaces with the hardware.  I am thinking specifically of the ability to program channels on Falcon / Zeus string controllers and setting / querying the parameters on devices like the Vast FMT-212.  It is a significant pain to have to dismantle some portion of the show and move it to a Windows PC in order to re-program some aspect of the hardware.

Offline 95CivicSi

  • Newbie
  • *
  • Join Date: Jul 2017
  • Location:
  • Posts: 1
  • Kudos: 0
Re: Sequencer integration APIs
« Reply #8 on: July 19, 2017, 02:46:12 PM »
Is there any documentation for the current API?

Offline darylc

  • Supporting Member
  • ******
  • Join Date: Oct 2013
  • Location: Australia
  • Posts: 111
  • Kudos: 3
Re: Sequencer integration APIs
« Reply #9 on: July 20, 2017, 07:03:08 AM »
Is there any documentation for the current API?

There is no current API, you ssh in and hack around the config files

 

Back to top