Complex IOT device

[skavan]

Hi,
I am almost certainly pushing this message in the wrong place....but have no idea where the right place is.
So feel free to kick me to the right place and close this "issue"...and apols for the clutter.
I have studied the docs (web things description) and many examples. But they are all rather simple devices.
A light switch, thermostat, dimmer and so forth.
I can find zero information on what the right approach to define a complex thing might be.

Example - an electronic keyboard.
It has 88 keys.
Keys can be On or Off. With additional properties, such as:

• AfterTouch (Pressure on the individual key).
• Pitch Bend (A modifier on all keys)
• Program Change (a modifier above Keys, that sets "Piano", "Organ" etc...)

I can't figure out what is a thing, what are properties and so forth.
Is an individual key (on the keyboard) a thing? If so, what is the collection of keys? And it's parent properties?
Or is the whole keyboard a thing?

End game - to define a schema/data model that describes a real-world complex electronic device.
While I picked a keyboard as the example, it could just as easily be a sprinkler system, with multiple sprinkler heads.
Or an LED strip, with multiple addressable LED's.

If someone could kick me to the right place to ask this...and/or give me some pseudo code to get started...would be really grateful.

Thanks.

[zolkis]

One could take an object-oriented approach, where a Thing (instance, object) has properties, actions (methods) and events.
I searched on "electronic keyboard api" and found a few things I didn't like that much, so here is my quick and erratic take, just out of my head :)

In this case, the electronic keyboard is a Thing.
Examples for properties: brand, make, manufacturer, serial, description, set of capabilities (modeled as array or rather, object), set of keys (as objects composed of name, base frequency, harmonics, waveforms, effects etc) etc.
Examples for actions:
on()
off()
hit(key, {options})
configure{options}
volume(percent)
mute()
unmute()
midi({options} (also see Web MIDI

Events:
onkeypressed (key, data)
onkeyreleased (key, data)

Sorry if it's inaccurate (and surely it's incomplete), I am not a musician. But in practice the OO design is quite well applicable when you define TDs (other might differ or warn about pitfalls - but as a start, try it) :).

[skavan]

@zolkis Thanks for taking the time on this.
I will kick off as you suggest and see where I end up!
What is the best place to post follow ups etc.. Is it here? or is there a forum somewhere?

s.

[egekorkan]

I think that the above proposal is very sound. The best place to discuss is indeed here, we do not use issues only for bug reports but for discussions as well :) Thank you for the input @skavan !

[skavan]

ok - so if you don't mind. let's play with this a little more...hopefully as a template for other complex cases.
First, let me describe the "Midi Keyboard".
It has two main components:

1. A Synthesizer. This is the component that generates sounds. Such as a Piano, or Organ or Flute etc... One can select sounds by command. example, Sound Bank A, Patch 1 is a Piano. It is connected to, but not required to be connected to:
2. A Keyboard. The keyboard generates notes (on, off). These notes may or may not be connected to the "Synthesizer" and may or may not be consumed by downstream devices. The keyboard can also receive notes.

For the sake of simplicity, let's ignore the Synthesizer (for now) and focus on the "Keyboard". In this "Synthesizer-less" mode..the keyboard is used to send "messages" to other devices.

The keyboard has up to 88 keys.
It is set to listen to a channel, and broadcast on a channel (1-16).
A key can be pressed (on), released (off), it has velocity and potentially pressure attributes.
At any given time, n keys can be "ON". where n is typically up to 16.
When a key is turned "on", it stays on until it is turned off.
So, hitting a key on the keyboard might trigger a message that looks like this (hex):
0x90 0x3C 0x64
Which means -- I am sending a note on (0x9x), on channel 0 (0x90). That note is 0x3C. It has been hit with a velocity of 100 (0x64).

To add some complexity, a follow on message might be triggered like: 0xA0 0x3C 0x7F --- which says (A0) aftertouch on Channel 1 (0) has been applied to note 3C with a pressure of 127 (7f). "Aftertouch" might cause the rendering synthesizer to play the note with vibrato.

And to add a final level of complexity, a follow on message might say: 0xe0 0x7f 0x7f, which says, apply Pitch Bend (e) to all notes on channel 1 (0) with a value of 7f 7f. (Pitch bend is when a note slides up or down - like a guitarist sliding a note). It doesn't apply to a single note -- but to all "on notes" on the specified "channel".

It is important to know that one doesn't need to track the state of 88 notes. But rather, only the notes that are on. And their attributes - where attributes maybe per "note" (i.e. aftertouch) or applied to all "on" notes. i.e. Pitch Bend.

OK - that's enough for this simplified (but reasonably complex model) model.
How might we describe it?

Now I will underwhelm you with:

{
  "id": "someuniqueURL",
  "title": "MidiKeyboard",
  "description": "Midi Keyboard",
  "properties": {
    "onKeys": {
      "type": "array",
      "title": "Keys",
      "description": "Keys On"
    },
    "lastKey": {
      "type": "object",
      "title": "Last Key Event"
    },
    "pitchBend": {
      "type": "integer",
      "title": "Pitch Bend",
      "minimum": 0,
      "maximum": 16383
    }
  }
}

My instinct is to create a property that is an array of "onKeys".
And each element would in onKeys would be an object like:

{
  "note": 0x3c,
  "channel": "0",
  "velocity": 0x64,
  "pressure": 0x32,
  "startTime": "2020-08-17T03:20:15.020Z"
}

I have no idea how to describe on the key value (above) in the schema (above above!).

Hope this makes vague sense and we can iterate to describe this example.

[takuki]

Hi @skavan, JSON schema provides a way to define arrays.
Please take a look at JSON schema documentation here.
I was not sure if this was what you were looking for in the above.

[sebastiankb]

@skavan please let me know if you question is answered and if I can close this issue.

[skavan]

Thx. I guess it has run it's course!