client registers, client events....

[pelikhan]

Let's talk about having virtual reg/command/events instructions in the spec to help high level code generation.

The current challenge is that the service definition is constrained to optimize 8bit firmware support and as such it ends being quite low level for some commands, like play tone which uses electrical terms rather musical terms. Client reg/commands/events can leverage additional code space/computation power to create high level APIs. This is an attempt to include this in the spec.

• "lowlevel register": don't generate high-level client code as this is a low-level command.

lowlevel register bits: buffer @ ...

• client commands/register/event: a command/register/event that is only implemented by the client services.

    command play_pulse { ..., lowlevel }

This command is not meant to be called directly from a client library.

    client ro pressed: bool 

The button is down. 

The register tracks the state of the button through the down, up events.

    client command play_note @ 0x81 {
        frequency: u16 Hz
        volume: u0.16 /
        duration: u16 ms
    } = play_tone(1000000 / frequency, 1000000 / frequency * volume / 2, duration)

Play a note at the given frequency and volume.

    client event click @ 0x185

Raised when there is an up event with less time than 200ms.

    awaitCondition(up.time < 200)
    raiseEvent(click)

PR #401

[pelikhan]

@tballmsft

[pelikhan]

@jamesadevine

[pelikhan]

By symmetry, we could use "server" to describe a command that's meant to be low level.

[mmoskal]

But it is used by client, but a low-level client...

[pelikhan]

#401

[tballmsft]

@ducky64 - Richard Lin - this conversation has been simmering for a while... as you know, we have a need to expose a better client-side experience. Your thoughts are welcome.

[ducky64]

I'm probably missing a lot of prior conversation, but my initial question is: I get the overall idea of flagging services / APIs as low-level, but what's the semantics you're going for and end-goal / use-case you're trying to achieve?

When not flagged as a client (so a 'server' / 'low-level' service), should it:

• (least-restrictive) be filtered out unless a user opts into some more advanced interface, to clean up the library interface for novice users (akin to some kind of "basic mode" - avoid clutter from lots of small, low-level services). Can also take other forms, like greying out, or being hidden behind a list expansion or something.
• be hidden in certain programming interfaces (eg, MakeCode) and with no ability to opt-in, mainly where the language is more geared towards beginners, or may have partially incompatible semantics (eg, the service is super timing sensitive and needs to be used with care). However, community users could still write libraries / applications against this low-level interface through lower-level languages.
• more akin to package-private or protected access modifiers for classes, where there is enforcement on who / what can call these services.
• (most-restrictive) purely an internal API (eg more akin to a HAL, to provide portability so one doesn't have to re-implement higher-level services from scratch), that can't be accessed from the network. Seems pretty limiting, but potentially necessary where things are super timing sensitive?

[mmoskal]

When something is marked as low-level the idea was to not generate blocks for it and de-prioritize it somehow in intellisense for text-based languages (eg by exposing it with names starting with _). That would be language-dependent.

The client annotation says that the API is implemented only client side (which can be in some cases also low-level).

Note that most registers/commands/events have no annotation (ie. they are still implemented server-side, but should not be considered low-level).

[ducky64]

So one potential issue may be what should be low-level or not? And this seems like something which may be very context-dependent - eg, someone using a button to trigger events may only be interested in an on-press event (edge-sensitive; so you can hide the read-value event), but the same button may also be useful for a hold interaction (level-sensitive, where you want the read-value event).

Similarly with the speaker - it seems like there's several possible levels of abstractions, and I'd imagine all but the first could be useful to application developers:

• single pulse (or waveform generation if you have an analog speaker; very latency sensitive for audio applications)
• play note - repeated pulse train, arguably pretty low-level but still useful
• play several notes - repeated play note, perhaps taking in some higher-level data structure that could be shared

Maybe a simple client / server flag is sufficient (though might be important to have guidelines for consistency - especially if community services are expected), but maybe this is calling for a more flexible categorization (with the downside of added complexity)?

[mmoskal]

I think that something that plays several notes is another layer of abstraction (eg a separate class that has a pointer to the client class), which may be best handled by relying on mechanism in the programming language used by the client device. I would be inclined to only introduce what we know is needed (and we know we don't want MakeCode blocks for certain APIs; we also do have a few examples of slightly higher level blocks).

[pelikhan]

In general, if we cannot mount a rich block editing experience on top of a command/register without additional annotations or extra code, it's low level. Basically, lowlevel means a high-level language will automatically produce a block that's unusable in a high level language and it will require customization.

The categorization can be decided by a few factors:

(1) In play_tone we describe an eletrical pulse to play a tone, whereas the tone should be described by a frequency/volume. So we mark it as low level. Nobody thinks in pulse width about music.
(2) the 7-seg segment looks at a bitfield to on/off bars. It's an encoding of rendering a number/text.
(3) It's lowlevel. The HID keyboard takes a selector/modifiers pair which has to be lookup in the HID specification; it's an encoding of something like "Ctrl + A". It's low level.
(3) the LED light animation API is mini-VM running commands on the lights. It's lowlevel