github.com/jingruilea/kubeedge@v1.2.0-beta.0.0.20200410162146-4bb8902b3879/docs/proposals/mapper-design.md (about)

     1  ---
     2  title: Mapper Design
     3  status: implementable
     4  authors:
     5      - "@sids-b"
     6      - "@m1093782566"
     7  approvers:
     8    - "@qizha"
     9    - "@rohitsardesai83"
    10  creation-date: 2019-02-23
    11  last-updated: 2019-02-24
    12  ---
    13  
    14  # Mapper Design
    15  
    16  ## Table of Contents
    17  
    18  * [Introduction](#introduction)
    19  * [Motivation](#motivation)
    20    * [Goals](#goals)
    21    * [Non\-goals](#non-goals)
    22    * [User cases](#user-cases)
    23  * [Proposal](#proposal)
    24  
    25  ## Introduction
    26  Mapper is an application that is used to connect and and control devices. Following are the responsibilities of mapper:
    27  1) Scan and connect to the device.
    28  2) Report the actual state of twin-attributes of device.
    29  3) Map the expected state of device-twin to actual state of device-twin.
    30  4) Collect telemetry data from device.
    31  5) Convert readings from device to format accepted by KubeEdge.
    32  6) Schedule actions on the device.
    33  7) Check health of the device.
    34  
    35  Mapper can be specific to a protocol where standards are defined i.e Bluetooth, Zigbee, etc or specific to a device if it a custom protocol.
    36  
    37  ## Motivation
    38  All devices can be connected and controlled by drivers provided by their vendor.
    39  But the message from the device need to be translated into a format understood by KubeEdge.
    40  Also there should be a way to control the devices from the platform. Mapper is the application that interfaces between KubeEdge and devices.
    41  There should be a standard design for mappers supported by KubeEdge for keeping them generic and easy to use. 
    42  
    43  ### Goals
    44  * A generic way to support multiple devices of different protocols by having a standard design for mappers provided by KubeEdge.
    45  * Easy to use Mapper design.
    46  * Open-up the possibility of having mapper SDK in future which can generate mapper based of configurable inputs.
    47  
    48  ### Non-goals
    49  * Impose restriction on users to follow this design while writing applications for their device.
    50  * Have a single application that supports multiple devices of different protocols. 
    51  
    52  ### User cases
    53  1) Manage expected/actual state of a device.
    54  2) Collect telemetry data from devices.
    55  3) Schedule actions and check health of the device.
    56  
    57  ## Proposal
    58  <img src="../images/proposals/mapper-design.png">
    59  
    60  Please find below the detailed explanation of each component of the mapper.
    61  
    62  **1) Action-Manager**: A device can be controlled by setting a specific value in physical register(s) of a device and readings can be acquired by getting the value from specific register(s).
    63  We can define an Action as a group of read/write operations on a device. A device may support multiple such actions. Each of these actions should be supplied through config-file to action manager.
    64  An Operation can be defined using below defined structure
    65  ```go
    66  // Operation is structure to define device operation
    67  type Operation struct {
    68  	// Action can be one of read/write corresponding to get/set respectively
    69  	Action string
    70  	// AttributeName is the name of the attribute where action is to be performed.
    71  	// for eg uuid in BLE, holding register in modbus
    72  	AttributeName string
    73  	// AttributeValue is the value of the Attribute.
    74  	AttributeValue string
    75  	// Value is the value to be written in case of write action
    76  	Value string
    77  }
    78  ```
    79  An Action is a set of operation(s) and can be defined using below structure
    80  ```go
    81  // Action is structure to define a device action
    82  type Action struct {
    83  	// Name is the name of the action
    84  	Name string
    85  	// Operations is the list of operations to be performed for performing this action
    86  	Operations []Operation
    87  }
    88  ```
    89  **2) Scheduler**: Scheduler is used to perform action(s) after defined intervals. Schedule can be defined using below structure
    90  ```go
    91  // Schedule is structure to define a schedule
    92  type Schedule struct{
    93  	// Name is name of the schedule. It should be unique so that a stop-chan
    94  	// can be made corresponding to name to stop the schedule.
    95  	Name string
    96  	// Frequency is the time in milliseconds after which this actions are to be performed
    97  	Frequency int 
    98  	// Actions is list of Actions to be performed in this schedule
    99  	Actions []Action
   100  }
   101  ```
   102  
   103  **3) Watcher**: Watcher has 3 responsibilities: 
   104  
   105  a) To scan devices(wireless)/wait for device to turn on(wired) and connect to the correct device once it is Online/In-Range. It can use MAC address or any unique address provided by devices. In case of wired devices, GPIO can be an option.
   106  
   107  b) Keep a watch on the expected state of the twin-attributes of the device and perform the action(s) to make actual state equal to expected.
   108  
   109  c) To report the actual state of twin attributes.
   110  
   111  **4) Data-Converter**: Data received from the devices can be in complex formats. eg: HexDecimal with bytes shuffled. This data cannot be directly understood by KubeEdge.
   112  The responsibility of data-converter is the convert the readings into a format understood by KubeEdge.
   113  Many protocols have a standard defined for the reading returned by the device. Hence a common/configurable logic can be used. 
   114  
   115  **5) Health-Checker**: Health-Checker can be used to periodically report the state of the device to KubeEdge.
   116  This can be an optional component as not all devices support health-checking. In-future can be extended to report battery-state, malfunctioning when kubeedge supports these attributes.
   117  
   118  **6) Controller**: Controller should expose API's for CRUD operations for managing Actions, Schedules, Watchers, Data-Converters, Health-Checkers.
   119  
   120  **7) Driver Interface**: Driver Interface is responsible for talking to the the actual device driver while performing an Action. Device drivers can be protocol specific or device specific depending on the type of the device. A corresponding interface should be present in the mapper to talk to the actual driver.