EDIT:
Official release of API doc
original post:
@embodme is there a document covering the API mode yet?
doesn’t have to be polished … just the basics would be fine, basic sysex for send/receive (I want to light the leds 
)
I could just start sniffing the midi, but or some pointers might save me a little time
how did you get your (brilliant ) vumeters working?
eheh second inline to ask for this 
well, actually happy accident (and a bit of a hack)
I did it in Gig Performer, but also tried the other day using AB Live.
@embodme have just sent me a link to an API document 
Im not sure, if they want it shared (as it may not be finished) and perhaps would prefer the official source is on their website or something.
(if they don’t mind me sharing I can post here, or i guess they will )
till then, anyone that wants it feel free to DM me.
I really, really, really hope they will provide a shortcut for lighting the LEDs. I mean it’s a thousand LEDs (wow!!) and how many colors? So how many (MIDI-)bytes do you need to handle that?
Do we really need to specify:
It just hurts my programmer-soul!
Just use e.g. PolyAftertouch messages and it slips like butter (or so we say in german)
in api mode, its sysex
but I think @keymanpal was controlling vumeters via cc (see above post, Im sure he will give details) - so I suspect, some/many of the elements in non-api mode are responding to the CC with colour changes.
(Im only now having some time to dig into this, so will have a play )
as for sysex api, Ive not get a doc for it
its actually a bit clever than just draw pixel.
as well as drawing a single pixel (which as you say would be a lot of data)
you can send it a messages to draw many pixels in one go, draw rectangles, clear zones.
and I assume this would be expandable by @embodme , as obviously the firmware is interpreting these sysex, to decide what to draw, e.g. they could add a ‘draw circle’ function.
of course, at the end of the day, its not a hi-res display, so drawing functions are going to be pretty limited, so its a good starting point.
(I suspect, Embodme will see how much the api is actually used by developers before expending too much dev effort on it - which is perfectly reasonable imho)
actually, thinking about this, we have already seen this…
if you send a note to a note type element (e.g. keyboard) it will indeed use this to light the relevant pad/key.
so I suspect generally, if you send at element the same message as it sends out, then it will respond in the same way as it if it had generated the message.
i.e. if you send a slider a value, it will set the slider to that value.
beyond that for custom usage, I think you have to use the api mode and sysex… there are just too many leds to address to use things like polypressure/cc - without having to use a bunch of midi channels - which is not particularly attractive esp. for a midi network that’s got mpe traffic on it.
yep, might called it Bi-directional MIDI
… of course, for ‘higher-level’ functions SYSEX is just fine. But i want control of individual LEDs in the most efficient way possible. And then methinks PolyAftertouch messages are the way to go, just because others like NoteOn or CCs are already used for feedback. Well, maybe PolyAftertouch is already used for feedback too, I don’t know, but I doubt it. And it would definitely unclutter the data-stream!
BTW. I changed the LinnStrument firmware to do exactly that, and it was about five or six lines of code
but polyat can only address 128 leds per channel…
thats absolutely fine for the Linnstrument, which has very few ‘cells’
but, for the Erae, we have 24 x 42, so thats 1008 = 8 midi channels!
then it’d be very inefficient to write a large number of pixels…
e.g. consider a simple 4x3 border (filled) , that 12 pixels , so 48 bytes of (poly at = 4 byte message)
of course, sysex has a bit of an overhead, in this api, id say around 20 bytes… but once you start writing more than a few (5?) pixels, that going to be offset.
also the ‘pixels’ on the Erae are RGB, so a single 7 bit value (as used with poly AT) is not enough to to represent this.
so to handle this properly with polyAT, you have to start introducing the concepts of colour palettes, which would have to be defined by sysex anyway.
that said, I think a default set of 128 colours could be chosen that would be reasonable in most cases.
so for many cases you’d not need this - I guess
anyway, Im sure Embodme could do it, if there was a demand…
but I personally am happy enough with sysex - the approach they have chosen seems to be much more suited for more general purpose application - and I think scales better.
but for sure, I can see some might think polyat messages are easier to deal with if you’re not used to using sysex, or using some kind of environment that doesn’t deal with sysex nicely.
…that’s why i spoke of individual-pixel control vs. ‘higher-level’ functions.
A 4x3 array is 36 (not 48) bytes with poly-at vs. around 240 bytes of sysex if you really control each pixel individually. Of course, once you have defined lines, regions, frames, maps and whatnot, it looks different and the Erae obviously already has all that code and decoding capabilities, so it makes perfect sense with sysex. But you certainly can’t do that with 5 lines of code, you need a parser, dispatcher … you name it.
And a bit is a bit is a bit. I don’t care if it means a channel, or a LED-address or whatever.
Of course this means stretching the definition of MIDI somewhat, but as long as it is strictly within the device, it can’t possibly hurt anything else.
I see your point with the demand, yes, but it is somewhat of a chicken/egg problem. As long as the possibility is not there, some smart things cannot be done. Without these, there is no demand.
And I’m only suggesting this very little added feature, not, it must be done this way, instead of sysex (…and I am used to sysex)
using usb midi protocol… all midi messages are sent as 4 byte packets.
(and there is handling of sysex which means these are sent in blocks of 4 bytes, so they don’t have the same 25% overhead that 3 byte midi message have)
anyway, at that point we are comparing apples n’ oranges, since the higher level functions do exist on the erae, so we would not use pixel by pixel painting.
so, we are back to :
poly at = ease of coding but limited functionality (no 24 bit colour, no ‘functions’)
sysex = more flexible , a bit more code to write
I think makes perfect sense to provide the more flexible approach first, so that it doesn’t ‘limit’ what we can do.
if there are some users that think sysex is going to prevent them from creating something, Id say, contact @embodme , to discuss with them the idea of a poly at mode.
(after all both could exist, so why not )
perhaps someone could also ‘mock it up’ on the client side (i.e. polyat <-> sysex bridge) …to demo how it might work - should be simple enough, given its pixel level.
btw: you’d also need to consider how the ‘finger stream’ would work as the api mode also uses sysex for that - id assume that’d be the same mapping, where value = pressure.
…uhh??
you lost me on that!
I don’t really care on how exactly MIDI bytes are transmitted, I’m happy others do!
But I sure do care how many MIDI-bytes I have to encode and how many the Erae has to decode …and how.
I see, it won’t probably happen, but one can dream 
Most grid devices that take sysex have a command to set individual colors for multiple LEDs. It just scales a lot better, looking at USB bottlenecks.
Here’s an example for Launchpad X:
I believe the Akai Fire is undocumented, but the protocol was very similar there. (Though, if I recall, that one lets you set full RGB values, where launchpad uses a lookup table.)
Can’t remember on Push.
Monome does the same (minus the sysex), but their OSC implementation maxes out at one 8x8 block at a time. But even there, where it’s decidedly not RGB, this proves noticably more responsive than painting individual LEDs.
Anyway… Mark already said there’s a message to send many LEDs in one go. Maybe I’m misreading that, but it sounds like what you’re looking for.
Just need to wait on the sysex documentation.
created a small (c++) API to encapsulate all this stuff… and created a small demo app
(thanks to @keymanpal for the matrix inspiration )
code is up on my GitHub, early days… but perhaps useful to others.
Yes, that’s a quite sensible and flexible approach. The sysex overhead is still there but this way doesn’t matter that much.
The sysex format was defined some 40 years before, where device-addresses had to be specified since you were lucky to even have a single MIDI-port.
Since nowadays every (USB)-device has a dedicated port, maybe it would be a good idea to have an option to shortcut the sysex-format like F0 F0 cargoload F7, skipping the device address?
By the way, Push uses note msgs to light the pads and is lightning fast, compared to the LinnStrument (not to say the LinnStrument is unusable, it is fine too)
honestly,I think we are beating a dead horse here…
@Dr_Loop if you want embodme to support another protocol, shoot them an email with a feature request.
as above, Ive got the api now exposed as a C++ library and been creating some tests and demo apps.
so from experience, I can tell you the response is absolutely fine - there is no issue sending a lot of data at it, it displays the stuff really quickly - and the approach @embodme has taken means they can extend the api to cover other drawing functions.
so looks good enough for my application needs … which is what matters to me.
if other devs, need different, just contact Embodme an email.
now… lets see what we can create with it
… since I don’t own a Touch and won’t buy it (yet), it’s the other way round, the horse is not yet born 
(…but may be they read this discussion and get some inspiration)
I’ve added the API link to the top post.
consider it pre-release.
when Embodme add it to their website, I’ll remove this put the official release
pre-release doc error (reported to @embodme )
boundary request response
api doc says DAT1 = 0x7f, DAT 2=0x01, zone, width, height
in reality it is
DAT1 = 0x7f, zone, width, height
so DAT2 does not exist.
clarifications:
some things I found ‘along the way’
if you find the same zone (id) on multiple layouts, only the LAST one will be used.
rgb values
so the doc kind of talks about these as 24 bit or 7bit, in practice the spec says they are 18bit - so 6 bit each, I believe the upper bits are not used.
fingersteam message
so this has 14 x 7 bit payload, but talks about return 3 floats… which is a bit odd.
14 x 7 = 98 bit.
given (here) a float is 4 bytes (32 bits), its only using 96 bits, and its assuming standard (IEEE?) float encoding of this data)
so we get something like
float xyz[3], unbit-ise (indata, insize (int8_t*) xyz);
(obviously this is pseudo code, excludes checks etc )
