OIC realistic example

[barbieri]

We should provide a realistic OIC sample where devices are discovered and paired to be used together without using node options to specify the other endpoint.

We should have a node type to discover OIC devices implementing a given interface. Once these are discovered, they are sent to a "selector" node type that will pick one. The selected one is persisted and then used by further actions specific to that device interface.

A suggested approach is for the OIC device discoverer to emit a custom information packet with an array of items, each being composed of an identifier, a human readable name and possibly an icon (or a type). Alternatively it may produce packets of a single item that are accumulated by the selector -- in this case the selector would need a RESET or CLEAR port to flush items.

The selectors should be generic and work with the packets specified above (they could live in Soletta's core and not in oic module). Two selectors we could offer by default are:

• HTTP selector: it will export a HTTP resource using sol_http_server_register_handler(). The GET can return a JSON with the available options and the current selection. The POST handler receives the device ID that should be selected. An externally provided HTML/JS/CSS set may be used to present this to the user.
  • Options:
  • path (string): the URL path to handle HTTP requests.
  • Input Ports:
  • ITEMS (custom packet): the options to be selected.
  • SELECTED (string): the previously selected item, if any.
  • Output Ports:
  • SELECTED (string): the selected identifier. Sent when user chooses via HTTP.
• String output + Buttons Input selector: it will format a string output with the available options. Input ports will handle "previous", "next" and "select".
  • Options:
  • columns (int): the number of columns in the display. Will be used to format the string, including auto-scroll.
  • rows (int): the number of rows in the display. If more than 1, will wrap lines.
  • title (string): if more than one row, this will be the contents of the first row. Otherwise will be the prefix of the only row in the string.
  • auto_scroll (boolean): if true and the contents doesn't fit in the columns, then each row will scroll.
  • circular (boolean): if true, this is a circular menu, after the last option it goes back to the first.
  • Input Ports:
  • ITEMS (custom packet): the options to be selected.
  • NEXT (any): change to the next item.
  • PREVIOUS (any): change to the previous item.
  • SELECT (any): select the current item.
  • ENABLED (bool): make the interaction possible, otherwise don't produce strings or process next/previous/select inputs. This is used because the node is not created and destroyed on demand, rather it will be enabled and disabled.
  • SELECTED (string): the previously selected item, if any.
  • Output Ports:
  • SELECTED (string): the selected identifier. Sent when user chooses via HTTP.
  • STRING (string): string with the contents, this can be fed to LCD displays such as `grove/lcd-string.

NOTE: this task doesn't need to implement all of the selectors, only one is enough. In such case please create a task for the other selector.

The result of the selector is to be persisted and feeded back to the selector.

The proposed test FBP is:

# Declare Nodes
oic_discoverer(oic/device-discoverer:interface="core.brightlight")
brightlight_selector(http-server/selector:path="brightlight-selector")
brightlight_selector_trigger(http-server/boolean:path="start-brightlight-selector",value=false)
brightlight_persistence(persistence/string:name="brightlight",storage="efivars")
brightlight(oic/client-brightlight)
light_switch(gpio/reader:pin=123)

# Connect Discovery, Selection and Persistence flows
brightlight_selector_trigger OUT -> ENABLED oic_discoverer
oic_discoverer ITEMS -> ITEMS brightlight_selector
brightlight_selector SELECTED -> IN brightlight_persistence
brightlight_persistence OUT -> SELECTED brightlight_selector
brightlight_persistence OUT -> DEVICE_ID brightlight

light_switch OUT -> POWER brightlight

When the user restart the device, then the oic_discoverer will be inactive (ENABLED=false), since brightlight_selector_trigger is false. Then the brightlight_selector has no items to show or to select. However brightlight_persistence has a value stored and will send an initial packet, that is fed to brightlight. Once the light_switch is pressed the light will turn on.

To select a new OIC device, the user should visit a HTML/JS page. This page will GET /start-bright-light-selector?value=true, this will start oic_discoverer (ENABLED=true), sending packets to brightlight_selector. The JS will keep polling GET /brightlight-selector and update the user interface. Once the user selects an item, the JS will POST /brightlight-selector?selected=XXX. Then the brightlight_selector validates this is a known ID and if so will send XXX on its SELECTED output port. This goes to brightlight_persistence that saves to EFI and then forwards XXX on its OUT port, that ends into brightlight's DEVICE_ID port.

NOTE: I'm not happy with brightlight_selector_trigger, particularly with it being a boolean. If the user closes the browser without setting it to false, then it will keep discovering. We can work-around this with a timeout and resetting it to false once the brightlight_selector sends a SELECTED id, but that's cumbersome. We need to find a better way :-( However the ENABLED port in the oic_discoverer matches nicely with the same-name port in the LCD selector above. It would be started (set to true) after some event (ie: long press) and would be reset to false once SELECTED is sent.

[barbieri]

@glima please consider helping with the String output + Buttons Input selector. You did the grove/lcd-string and this selector output should be something we feed to that node.

[bdilly]

We may use it on foosball demo. I've added an OIC interface so table can talk to scoreboard. No pairing was implemented.