Project: Shifu (Provisioning / Automation & Configuration)
File: design-shifud.md

- - - - - - - - - - - This is a high-level design document for *shifud component of the Shifu framework. shifud is a daemonset that runs on every edgeNode. It discovers devices from a list of devices configured in Kubernetes' edgeDevice* resource and update relative resources to kube-apiserver. *shifud's foremost job is to make edgeDevice discovery and verification as easy as possible. Developers should't need much configuration to make their edgeDevice available in Shifu*. Here are a few design requirements: *shifud should be able to discover edgeDevices* with ONVIF or similar protocols automatically, without much user/developer intervention. Developer should only need to provide necessary information in order for *shifud* to discover a specific devices. *shifud should be able to run on its own as soon as Shifu* framework is up. *shifud should consume minimum amount of resource on each edgeNode* and across the cluster. *shifud* should be able to handle the majority of IoT protocols. [None] *deviceDiscoverer is a process that continuously scans for device events on edgeNode*, including but not limited to network reachability, USB event. *deviceVerifier is a process that interacts with edgeDevice and tries to populate and verify their metadata to match Kubernetes' edgeDevice* resources. *deviceUpdater updates edgeDevice resource to kube-apiserver based on the edgeDevice*'s verification status. The overall input and output of *shifud* can be summarized in the following graph: ](/img/shifud-input-output.svg) The input to *shifud from Kubernetes edgeDevice resource should be a list of edgeDevices*: ``` apiVersion: v1 kind: edgeDevice metadata: name: franka-emika-1 spec: sku: "Franka Emika" connection: Ethernet status: offline address: 10.0.0.1:80 protocol: HTTP disconnectTimeoutInSeconds:600 # optional group:["room1", "robot"] # optional driverSpec: # optional when no driver is required instructionMap: # optional move_to: api: absolute_move # API of the driver ...... ``` ](/img/shifud-design-overview.svg) Upon querying the list of devices, *deviceDiscoverer* starts local scanning using ethernet protocols. The following protocols should be supported: ``` ONVIF SNMP MQTT OPC UA PROFINET ``` Upon receiving the list of devices, *deviceDiscoverer* starts local scanning using different protocols. The following protocols should be supported: ``` udev MODBUS ``` The discovery process depends on the protocol: For TCP/IP type of edge devices, ping/TCP connect can be use directly. For udev/USB type of edge devices, *deviceDiscoverer* will utilize Linux's tool. Once the device has been discovered, *deviceVerifier* will then start matching the device metatdata with device list through its connection protocol. ``` sample udevadm output: E: DEVNAME=/dev/video3 E: SUBSYSTEM=video4linux E: IDSERIAL=SonixTechnologyCo.Ltd.USB2.0Camera_SN0001 ``` Once the verification is done, *deviceUpdater will update the edgeDevice*'s resource to Kubernetes API server. ``` apiVersion: v1 kind: edgeDevice metadata: name: franka-emika-1 spec: sku: "Franka Emika" connection: Ethernet status: online address: 10.0.0.1:80 protocol: HTTP disconnectTimeoutInSeconds:600 # optional group:["room1", "robot"] # optional driverSpec: # optional when no driver is required instructionMap: # optional move_to: api: absolute_move # API of the driver ...... ```