provide a query to report pin values in bulk

[soundanalogous]

There already exists the Pin State Query which reports the output state (which is also the value) of a specified pin. There is also a use case for querying input values - especially when using non-serial transports. The Pin State Query is also inefficient when reporting several pins since the query is on a per pin basis.

The following proposal adds the ability to query the values of a range of pins including all pins, all input, all output, all digital input, all analog input, all digital output and all analog/pwm output.

Reporting of input pins would simply report the input pin value via the existing DIGITAL_MESSAGE or ANALOG_MESSAGE commands immediately upon receipt of the query. This is already done per pin (or port) when analog or digital pin reporting is enabled, but this proposal extends the ability to report at any time the user requests it - especially useful in the event that the transport connection was reestablished.

Reporting of output pins could use the Pin State Query Response, iterating over the output pins and sending the response for each pin.

0  START_SYSEX        (0xF0)
1  PIN_VALUE_QUERY    (0x68)
2  type                0 = all pins, 1 = all input, 2 = digital input, 3 = analog input,
                       4 = all output, 5 = digital output, 6 = analog output / pwm
3  END_SYSEX

Some additional types could be pin (input & output), pin_input, pin_output and then the following byte would be the pin number. Not sure if this would actually be useful, but it could be added later if a use case arises.

[jnsbyr]

I support this proposal. The type parameter give the host all necessary control depending on the application. The pin type should be included from the beginning.

[soundanalogous]

0  START_SYSEX        (0xF0)
1  PIN_VALUE_QUERY    (0x68)
2  type                0 = all pins (input & output),
                       1 = all input, 2 = digital input, 3 = analog input,
                       4 = all output, 5 = digital output, 6 = analog output / pwm
                       7 = pin (input & output), 8 = pin input, 9 = pin output
3  pin                (0-127) // only use if type > 6
4  END_SYSEX

[jnsbyr]

What is the difference between pin X, pin input X and pin output X? Will there be no reply if X is configured as output and the query is for pin input?

[soundanalogous]

Good point. pin alone is probably sufficient then. There are also cases when a pin is neither configured as input or output (I2C for example) and in that case if the user submitted a query for that pin, nothing would be returned.

[soundanalogous]

0  START_SYSEX        (0xF0)
1  PIN_VALUE_QUERY    (0x68)
2  type                0 = all pins (input & output),
                       1 = all input, 2 = digital input, 3 = analog input,
                       4 = all output, 5 = digital output, 6 = analog output / pwm,
                       7 = pin
3  pin                (0-127) // only use if type > 6
4  END_SYSEX

[rwaldron]

Here are some scenarios that I think are obvious and that I've already answered and understood, but I would appreciate your confirmation :)

When I send...

• [START_SYSEX, PIN_VALUE_QUERY, 0b10000000, 2, END_SYSEX]... I will receive a DIGITAL_MESSAGE response with the state of port 0
• [START_SYSEX, PIN_VALUE_QUERY, 0b00000100, END_SYSEX]... I will receive x DIGITAL_MESSAGE responses, where n is the number of ports that contain pins of which I've previously sent [PIN_MODE, p, 0x00]
• [START_SYSEX, PIN_VALUE_QUERY, 0b00001000, END_SYSEX]... I will receive n ANALOG_MESSAGE responses, where n is the number of A* input pins of which I've previously sent [PIN_MODE, p, 0x02]

If all of those are true statements, then I feel confident in my understanding of the proposal.

With regard to 6 = analog output / pwm,, this is entirely new, so there is no existing response type for it. Reusing ANALOG_MESSAGE (which I'm not recommending), then you will have two value ranges: 10-bit and 8-bit (eg. on Arduino UNO, that will likely varying further in future). I'm not sure what this means or if it's even important, I'm just thinking out loud

[jnsbyr]

My first impression of the proposal was that the "pin" parameter is always part of the message but zero is not an invalid pin number on all platforms so it cannot be used as a wildcard. Either the pin parameter is defined as optional or a value like 0x7F is defined as wildcard for "all pins".

With [START_SYSEX, PIN_VALUE_QUERY, type=2, pin=7, END_SYSEX] you should get a DIGITAL_MESSAGE response with the state of port 0 if pin 7 is configured as digital input.

Looking at the specs I think using ANALOG_MESSAGE to report type 6 is not possible because the pin range is limited to 16. This is enough for analog inputs but there is no room for mapping additional analog/pwm inputs (at least on some boards). For type 6 the pin state response 0x6E could be used and it can handle any kind of pwm resolution because of its extensible definition.

[soundanalogous]

That's correct, pin state response (0x6E) would be used to report analog out / pwm value. It would also be used to report the digital out value since you would not want to receive a DIGITAL_MESSAGE on the host for an output pin.

[jnsbyr]

I see no conflict using DIGITAL_MESSAGE to report digital output pins. The message is port oriented anyway and a port may contain an arbitrary mix of inputs and outputs pins. Using this message would reduce the overhead in transmission and decoding. Even existing host applications know which pin of a port is input or output. Existing host code for updating digital inputs could be reused for the outputs.

[rwaldron]

W/r to my notes re: analog/pwm output values—I completely forgot that 0x6E messages would include that information—sorry for the confusing comment.

[soundanalogous]

There is probably no conflict as long as the host is properly filtering the port values. I'm just saying the pin state query response is already set up to report the digital output pin values and if a host cares to know this value for an individual pin it already has a mechanism to do so rather than having to add new logic to try to get that value from an incoming DIGITAL_MESSAGE which is currently only used in host libraries (to my knowledge at least) to parse digital input data (not output).

[soundanalogous]

sending a pin value query for a digital input pin on the other hand would return a DIGITAL_MESSAGE

[jnsbyr]

Lets define the reply messages in a list for each request type:

• type 2 -> digital message 0x90 (for all ports with digital input pins)
• type 3 -> analog message 0xE0 (for each pin)
• type 1 -> type 2 + type 3
• type 5 -> digital_message 0x90 (for all ports with digital output pins) or pin state query response 0x6E pin mode 1 (for each pin)?
• type 6 -> pin state query response 0x6E pin mode 3 (for each pin)
• type 4 -> type 5 + type 6
• type 0 -> type 1 + type 4
• type 7 -> type 2, 3, 5 or 6 depending on pin type

I agree that hosts who have already implemented the pin state query response need no changes to process the replies for type 5 and 6. On the other hand port reporting for type 5 has slightly less overhead.

[soundanalogous]

I agree that there is less overhead in using DIGITAL_MESSAGE to report output values, but there is also added overhead in parsing the result, especially in that 99% of the time you receive DIGITAL_MESSAGE you only care about the input state. If there is no loss of connection the host should always know the state of digital output (since the host set that pin state). If you need to ensure this state is correct after a RECONNECT event then you would have to assume the next DIGITAL_MESSAGE received, following a PIN_VALUE_QUERY is the message you need to parse the output values from and update the local state of that pin (if you use a pin object in the host for example). However when using PIN_STATE_RESPONSE, there is no guessing about when to update the output pin state in the host application.