Commit 636c4e15 authored by Sukru Senli's avatar Sukru Senli
Browse files

update README for doc portal

parent d055dd8a
Pipeline #17342 passed with stage
in 7 seconds
## Peripheral-manager
# Peripheral Manager
Peripheral-manager is a user space process and presents an api via ubus objects.
`peripheral-manager` is the GPIO manager controlling buttons and LEDs. It abstracts the physical leds into functions.
That way the OS can have an uniform API across devices. `peripheral-manager` also supports several ways
to integrate LEDs and buttons but presents them through a common API.
![peripheral-manager__1_](/uploads/edf20a87e3693ada6f6a996b176e4965/peripheral-manager__1_.png)
The buttons and LEDs are configured dynamically from the /etc/board-db/config/hw file. Buttons can also be added from the /etc/config/buttons file,
this to add the option to configure enabled buttons from the configuration interface.
Peripheral-manager uses modules for each api it supports.
![peripheral-manager](./img/peripheral-manager.png)
`peripheral-manager` uses modules for each API it supports.
Current support contains the following:
* Broadcom gpio leds
* Broadcom led controller
* Broadcom gpio buttons
* Semtech i2c led/touch controller
* Linux kernel gpio leds/buttons
* SPI based led controller
* Linux Kernel GPIO LEDs/Buttons
* Broadcom LED controller
* Semtech I2C LED/Touch controller
* SPI based LED controller
* I2C based SFP handler
Peripheral-manager continously polls/updates the state of the hardware a few times per second.
Because of that it can only handle things that doesn't need real-time behaviour. So
amongst the leds the ethernet link indicator and traffic leds are controlled
by the hardware.
`peripheral-manager` continously polls/updates the state of the hardware a few times per second.
Because of that it can only handle things that doesn't need real-time behaviour. So,
the ethernet link indicator and traffic LEDs are controlled by the hardware.
The operation of peripheral-manager is as following:
The operation of `peripheral-manager` is as following:
* Load configuration section for each peripheral
* Create peripheral ubus object
* Link actions to object
* Continously poll hardware for state changes or ubus object changes
* Continously poll hardware for state changes
* Act on changes
## Buttons
### Buttons
Button objects use simple logic. A gpio state change or register change in a touch
controller will be detected by the polling loop and then the corresponding action
is performed. It is also possible to call the object to perform a virtual press
of the button to trigger the actions the button press is supposed to perform (not part of the 4.4 release).
of the button to trigger the actions the button press is supposed to perform.
Example button configuration from /etc/board-db/config/hw
```
config gpio_button 'gpio_buttons'
list buttons 'gpio_reset'
list buttons 'gpio_wps'
config gpio_button 'gpio_reset'
option addr '46'
option active 'low'
config gpio_button 'gpio_wps'
option addr '41'
option active 'low'
config button 'reset'
list button 'gpio_reset'
option minpress '5000'
option hotplug 'resetbutton'
```
To observe button presses the best way is to run logread -f to tail the syslog.
To observe button presses the best way is to run "logread" -f to tail the syslog
or run "ubus listen button.*" to listen to button ubus events.
### Leds
## LEDs
Leds doesn't have a single relation between one hardware led and the function it represents.
To handle the relations that are present the concept of led functions are introduced.
......@@ -49,7 +73,31 @@ over ubus. What peripheral-manager does at startup is that it loads a configurat
describes the hardware connection of the leds and how to map them to the functions. When the function objects
states are changed peripheral-manager then performs the correct hardware io-operation.
#### Function objects
Example LED configuration from /etc/board-db/config/hw
```
config gpio_led 'red_status'
option sysfs_attr 'red:status'
option active 'hi'
option mode 'led_linux'
config gpio_led 'green_status'
option sysfs_attr 'green:status'
option active 'hi'
option mode 'led_linux'
config led_map 'led_status'
list led_action_ok 'green_status=ON'
list led_action_ok 'red_status=OFF'
list led_action_off 'green_status=OFF'
list led_action_off 'red_status=OFF'
list led_action_notice 'green_status=FLASH_SLOW'
list led_action_notice 'red_status=FLASH_SLOW'
list led_action_alert 'green_status=OFF'
list led_action_alert 'red_status=FLASH_SLOW'
list led_action_error 'green_status=OFF'
list led_action_error 'red_status=FLASH_FAST'
```
The led function objects have one main parameter and that is the state of the function.
......@@ -61,8 +109,6 @@ The led function objects have one main parameter and that is the state of the fu
The above list are the currently supported states.
#### Hardware leds
The physical leds have actions performed on them.
* ON
......@@ -73,20 +119,53 @@ The physical leds have actions performed on them.
The above list are the currently supported actions.
For example the voice led function state NOTICE
can have a physical led with the action FLASH_SLOW mapped to it. Peripheral-manager
can have a physical led with the action FLASH_SLOW mapped to it. `peripheral-manager`
would then make sure that the led continously is blinking until some other state
is set for the voice led function.
A graphical representation would look like the following.
![ubus_objec_mapping](/uploads/071032353988e0611f328cf0f637b72c/ubus_objec_mapping.png)
![peripheral_led_mapping](./img/peripheral_led_mapping.png)
## SFP Support
### SFP
Peripheral-manager supports reading of the SFP ROM and DDM data over an I2C bus. The data can be queried over ubus.
The sfp objects mainly present the sfp rom and ddm values in a user readable way over ubus.
The following command will list all available rom object methods:
```
ubus list -v sfp.rom
'sfp.rom' @48feb720
"get-type":{}
"get-connector":{}
"get-ethernet":{}
"get-encoding":{}
"get-rate":{}
"get-length":{}
"get-vendor":{}
"get-oui":{}
"get-pn":{}
"get-rev":{}
"get-sn":{}
"get-date":{}
"get-ddm":{}
"get-all":{}
```
Changeing rom to ddm with get the ddm object methods:
```
ubus list -v sfp.ddm
'sfp.ddm' @7ba2fcb2
"get-rx-pwr":{}
"get-tx-pwr":{}
"get-current":{}
"get-voltage":{}
"get-all":{}
```
The following command will query the sfp for all rom parameters:
```
ubus call sfp.rom get-all
{
"connector": "SC",
......@@ -104,360 +183,17 @@ ubus call sfp.rom get-all
}
```
## Task / Prerequisite
As example task we will create a configuration that makes it possible to control some
of the leds via the 3 buttons on the DG400PRIME hardware.
This task is best done iteratively directly on the hardware. When everything is working
the way it should the configuration file can be committed to build system targets git repository.
Currently target/linux/iopsys-brcm63xx-arm/base-files/lib/db/boards/DG400PRIME.
The DG400PRIME board has 4 physical buttons and 16 physical leds. The buttons and leds
all use the direct gpio block. The buttons use address 32-35 and the leds use address 76-91.
(Other types of connections are supported as long as there is corresponding driver code.)
To setup the hardware for the example task edit the running board file and remove the
config by the following commands:
```
vi /lib/db/config/hw
```
Then erase the button and leds configuration by the following commands:
```
:84,400d
:wq
```
Now reboot the device with:
```
sync
reboot
```
To revert the changes just perform at default reset by running the command:
```
defaultreset
```
## Schematics for training
In the following exercise we are going to use both LEDs and buttons. The schematics below illustrates how the LEDs and buttons are connected to the SoC.
All LEDs and buttons are not shown in the scehamtics.
![Schematics](media/schematics-training.png)
## Leds
For the task we will only configuring 10 of the 16 leds. Add the following text block to
the running board configuration file (/lib/db/config/hw).
```
config gpio_led gpio_leds
list leds Status_green
list leds Status_red
list leds Broadband_green
list leds Broadband_red
list leds Internet_green
list leds Internet_red
list leds Voice_green
list leds Voice_red
list leds Ext_green
list leds Ext_red
```
This will enumerate all the physical leds we want to use
(the idea here is that you use the names from the schematics).
The next block will declare the configuration to be used for each led.
Depending on the led connection type the option parameters will be different.
The configuration name gpio_led means that in this case the led is connected
to a gpio pin on the SoC. The mode setting direct means that there is no
led controller or shift register in the way but only a direct gpio connection.
The option name active tells the polarity of the gpio pin and addr ensures that
the led can be addressed. Different api modules can have other configuration
options but they all have some kind of way to address the individual leds.
```
config gpio_led 'Status_green'
option addr '76'
option active 'hi'
option mode 'direct'
config gpio_led 'Status_red'
option addr '77'
option active 'hi'
option mode 'direct'
config gpio_led 'Broadband_green'
option addr '78'
option active 'hi'
option mode 'direct'
config gpio_led 'Broadband_red'
option addr '79'
option active 'hi'
option mode 'direct'
config gpio_led 'Internet_green'
option addr '80'
option active 'hi'
option mode 'direct'
config gpio_led 'Internet_red'
option addr '81'
option active 'hi'
option mode 'direct'
config gpio_led Voice_green
option addr 82
option active hi
option mode direct
config gpio_led Voice_red
option addr 83
option active hi
option mode direct
config gpio_led Ext_green
option addr 84
option active hi
option mode direct
config gpio_led Ext_red
option addr 85
option active hi
option mode direct
```
And now we need to map everything together. A state in an function object might turn on one led
and turn off another. To configure that we use the actions that are available.
This first thing to add is the led functions we want.
```
config led_map led_map
list functions status
list functions broadband
list functions internet
list functions dummy
```
We add one extra dummy led function for testing purposes.
In the next step we map the functions states to different led actions.
```
config led_map led_internet
list led_action_ok 'Internet_green = ON'
list led_action_ok 'Internet_red = OFF'
list led_action_off 'Internet_green = OFF'
list led_action_off 'Internet_red = OFF'
list led_action_notice 'Internet_green = FLASH_SLOW'
list led_action_notice 'Internet_red = OFF'
list led_action_alert 'Internet_green = OFF'
list led_action_alert 'Internet_red = FLASH_SLOW'
list led_action_error 'Internet_green = OFF'
list led_action_error 'Internet_red = ON'
config led_map led_status
list led_action_ok 'Status_green = ON'
list led_action_ok 'Status_red = OFF'
list led_action_off 'Status_green = OFF'
list led_action_off 'Status_red = OFF'
list led_action_notice 'Status_green = FLASH_SLOW'
list led_action_notice 'Status_red = FLASH_SLOW'
list led_action_alert 'Status_green = OFF'
list led_action_alert 'Status_red = FLASH_SLOW'
list led_action_error 'Status_green = OFF'
list led_action_error 'Status_red = FLASH_FAST'
config led_map led_broadband
list led_action_ok Broadband_green=ON
list led_action_ok Broadband_red=OFF
list led_action_off Broadband_green=OFF
list led_action_off Broadband_red=OFF
list led_action_notice Broadband_green=FLASH_SLOW
list led_action_notice Broadband_red=OFF
list led_action_alert Broadband_green=FLASH_SLOW
list led_action_alert Broadband_red=OFF
list led_action_error Broadband_red=ON
list led_action_error Broadband_green=OFF
config led_map led_dummy
list led_action_ok Voice_green=ON
list led_action_ok Ext_green=OFF
list led_action_off Voice_red=OFF
list led_action_off Ext_green=OFF
list led_action_notice Ext_green=FLASH_SLOW
list led_action_notice Ext_red=FLASH_FAST
list led_action_notice Voice_green=ON
list led_action_notice Voice_red=FLASH_FAST
list led_action_alert Ext_green=FLASH_SLOW
list led_action_alert Ext_red=OFF
list led_action_error Voice_green=ON
list led_action_error Voice_red=FLASH_SLOW
list led_action_error Ext_green=OFF
list led_action_error Ext_red=ON
```
Save the changes and reboot the device.
```
sync
reboot
```
Now that we have abstracted the led functions from the physical leds we can on the
software side set the ubus objects to different states without the knowledge of what
leds are actually present or what hardware configuration it uses.
To list the ubus objects use the ubus list command:
```
root@iopsys:~# ubus list led.*
led.broadband
led.internet
led.status
led.dummy
```
To query an individual objects status use the follwing command:
```
root@iopsys:~# ubus call led.internet status
```
It should give the following output:
The following command will query the sfp for all ddm parameters:
```
ubus call sfp.ddm get-all
{
"state": "off",
"brightness": 100
"voltage": "3.2376 V",
"current": "30.864 mA",
"tx-pwr": "0.3012 mW",
"tx-pwr-dBm": "-5.2115 dBm",
"rx-pwr": "0.0002 mW",
"rx-pwr-dBm": "-36.9897 dBm",
"rx-pwr-type": "average"
}
```
To now control a led function the following command can be used:
```
ubus call led.internet set "{\"state\" : \"OK\"}"
```
The states can be changed to the following:
```
OFF, OK, NOTICE, ALERT, ERROR
```
If you try the led.dummy object you can get some weird behavior. That is because
the logic flow is not complete. It is up the developer to make sure it make sense.
And that no physical led is forgotten.
Other parts of the system have implemented logic for driving specific led functions.
The only thing needed to reuse that is by configuring a led object with the name
it uses. It is also possible to create virtual object so
that one led position on the hardware device can be shared between 2 led functions,
for example the wifi and wps functions. One just have to map out a complete led
flow for the logic states.
## Buttons
Buttons are also configured from
the board file. So we will add the configuration by adding the following to the running
board file.
```
vi /lib/db/config/hw
```
The following will declare the board configuration. In this case the buttons
are directly connected to the SoC via gpio pins. The same options names as the
leds are used.
```
config gpio_button gpio_buttons
list buttons gpio_reset
list buttons gpio_wifi
list buttons gpio_wps
list buttons gpio_dect
config gpio_button gpio_reset
option addr 32
option active low
config gpio_button gpio_wifi
option addr 33
option active low
config gpio_button gpio_wps
option addr 34
option active low
config gpio_button gpio_dect
option addr 35
option active low
```
And to link an action to a button the following is added:
```
config button RESET
list button gpio_reset
option minpress 5000
option hotplug resetbutton
config button WPS
list button gpio_wps
option minpress 500
option hotplug test1button
config button DECT
list button gpio_dect
option minpress 5000
option hotplug test2button
```
When pressing a button an ubus event is generated and a hotplug event. (By executing a system() call.)
The hotplug event can picked up in the hotplug button configuration file:
```
vi /etc/hotplug.d/button/10-button
```
At the end of the file add the following lines:
```
[ "test1button" == "$INTERFACE" ] && {
ubus call led.internet set "{\"state\" : \"OK\"}"
}
[ "test2button" == "$INTERFACE" ] && {
ubus call led.internet set "{\"state\" : \"OFF\"}"
}
```
Restart the peripheral manager:
```
/etc/init.d/peripheral_manager stop
/etc/init.d/peripheral_manager start
```
And now it should be possible to turn on the internet led by pressing the wps button
for half a second but to turn it off you have to press the dect button for more
then 5 seconds.
A graphical flow chart of the task logic can be seen below.
![Flowloop](/uploads/66fb553dc98affb06d2f05e2e29764a8/Flowloop.png)
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment