Support for Device Indicators Style Info

[landlessness]

How do we transform a flat list of device indicators like state (which for a pure sensor has very little useful info) and intensity (which for a sensor might have all the useful info) into a meaningful UI with the proper order, display format, units and significant digits?

For a typical device here are the questions we want to answer:

• in which order should the device indicators be displayed?
• should any indicators be hidden?
• in what format should we display each indicator?
• what are the units of the indicator?
• what is the display label of those units?

The mock photocell (light sensor) is currently using the following values to answer those questions:

"style" {
  "displays": [
    {
      "indicator": "state",
      "display": "none"
    },
    {
      "indicator": "intensity",
      "display": "billboard",
      "position": 10,
      "significantDigits": 3,
      "symbol": "lx"
    },
    {
      "indicator": "intensity",
      "display":"lineChart",
      "position": 20,
      "significantDigits": 3,
      "symbol": "lx"
    }
  ]
}

In this case the state indicator is not displayed at all. While the intensity indicator is displayed in the top (0) position. The display format of the intensity indicator is billboard, it should be displayed with 3 significant digits (0.14 instead of 0.1369745962155623) and a units label of lx (units name and quantity can be ignored for now). We will have to define formally what billboard means, but essentially the idea is to display the value as large as possible within the given space.

[benpackard]

Maybe a dumb question, but has any discussion been given to moving the onus on to the provider to define their own display content's format directly? In other words, instead of setting a specific set of elements (name, symbol, significant digits), what do we lose by having them set a single displayLabel (e.g. "0.14 lux"), plus of course the display type (billboard)? Perhaps the raw value itself (0.1369745962155623) would also be sent to allow for graphing, etc.

[landlessness]

good question @benpackard. the values will be streaming in via a websocket. and they will also need to be plottable on a graph so having the labels separate from the values is pretty important IMO. Your question tho is actually making me rethink some other aspects of this. I'm going to noodle some more. I might make some edits to the enhancement request.

[landlessness]

@benpackard as a philosophy do we want the API to be semantically rich? or just send display values? when we think about localization, orders of magnitude of units, translating among different units of the same quantity (kilometers and miles for distance, etc ). etc. I err on the side of being semantically rich.

[landlessness]

FYI right now I'm thinking about the best way to indicate that we want intensity to show both a big number in a billboard on top and a line chart just below it.

[chadalderson]

To build on @benpackard a little bit more (and specifically around the "display order" of devices), can the onus be put on the developer? Information Architecture is somewhat subjective (to a degree) so I know that people are going to want to be able to control the order of UI controls within a device's view. For now, a simple stacked/pancake order is probably good. I've seen templates that use an integer 1-N to control this. What ends up happening is people use increments of 10 (10, 20, 30...) for the sort order. This way it gives them a buffer if they want to drop something in down the road and don't need to change the order property of every control...

[landlessness]

@benpackard I just edited the API. it doesn't directly correspond to your suggestion, but your question did make me adjust the approach to handle both a billboard and a graph for the same indicator. i'm reluctant to entangle the unit symbol and the value for the reasons I gave above. If I'm missing the point, please holler.

@chadalderson i also edited the API to include what I think was your point about creating space between the positions 10, 20, etc. instead of just 0, 1 as I had it originally.

[landlessness]

also, @benpackard and @chadalderson, you used the language vendor and developer above. I think I got the meaning from the context.

however, let's aim for greater precision in our language. there is only one stakeholder in the REST client-server system we are creating. That persona is the API Developer. Once we are done and the app is in the app store, that's it. The API Developer runs the entire show via the REST API.

We see that the same way? There can only be one?

[benpackard]

@landlessness Yep, I I was just trying to distinguish from potential app developers who might be adapting our iOS app or integrating ZettaKit themselves directly. API Developer makes sense to me.

[benpackard]

@landlessness @chadalderson What is the value of display_order here vs relying on the order in which the API lists the indicators? Is that seen as too implicit/relying too much on an internal detail?

[landlessness]

Another good question, @benpackard. Here's my thought process: the indicators are in the properties dictionary / hash of the API. But dictionary / hash keys are unordered collections in most web APIs and in most languages (like JavaScript). So we can't count on the order of the keys. Also, in the case of Zetta, some of those indicators (like state and name) are auto-generated by the underlying platform so the API developer has no means to change the order. Finally there is often very little semantic meaning of the order of the indicators whereas the style meaning can be very high. So putting the order in the style metadata should solve for the known issues within the platform and API constraints we have. Let me know if you have other thoughts.

[landlessness]

@benpackard good point on the OS Dev who forks the Zetta sample app. that's an important role. Can we call him forker?

[benpackard]

@landlessness Thanks for the thorough explanation. And yep, forker works.

[benpackard]

Photocell is up and running as a working example of this.