Merge pull request #1259 from jow-/introduce-nlbwmon
[project/luci.git] / applications / luci-app-wifischedule / README.md
1 # wifischedule
2 Turns WiFi on and off according to a schedule on an openwrt router
3
4 ## Components
5 * wifischedule: Shell script that creates cron jobs based on configuration provided in UCI and does all the other logic of enabling and disabling wifi with the use of `/sbin/wifi` and `/usr/bin/iwinfo`. Can be used standalone.
6 * luci-app-wifischedule: LUCI frontend for creating the UCI configuration and triggering the actions. Depends on wifischedule.
7
8
9 ## Use cases
10 You can create user-defined events when to enable or disable WiFi. 
11 There are various use cases why you would like to do so:
12
13 1. Reduce power consumption and therefore reduce CO2 emissions.
14 2. Reduce emitted electromagnatic radiation.
15 3. Force busincess hours when WiFi is available.
16
17 Regarding 1: Please note, that you need to unload the wireless driver modules in order to get the most effect of saving power.
18 In my test scenario only disabling WiFi saves about ~0.4 Watt, unloading the modules removes another ~0.4 Watt.
19
20 Regarding 2: Think of a wireless accesspoint e.g. in your bedrom, kids room where you want to remove the ammount of radiation emitted.
21
22 Regarding 3: E.g. in a company, why would wireless need to be enabled weekends if no one is there working? 
23 Or think of an accesspoint in your kids room when you want the youngsters to sleep after 10 pm instead of facebooking...
24
25 ## Configuration
26 You can create an arbitrary number of schedule events. Please note that there is on sanity check done wheather the start / stop times overlap or make sense.
27 If start and stop time are equal, this leads to disabling the WiFi at the given time.
28
29 Logging if enabled is done to the file `/var/log/wifi_schedule.log` and can be reviewed through the "View Logfile" tab.
30 The cron jobs created can be reviewed through the "View Cron Jobs" tab.
31
32 Please note that the "Unload Modules" function is currently considered as experimental. You can manually add / remove modules in the text field.
33 The button "Determine Modules Automatically" tries to make a best guess determining regarding the driver module and its dependencies.
34 When un-/loading the modules, there is a certain number of retries (`module_load`) performed.
35
36 The option "Force disabling wifi even if stations associated" does what it says - when activated it simply shuts down WiFi.
37 When unchecked, its checked every `recheck_interval` minutes if there are still stations associated. Once the stations disconnect, WiFi is disabled.
38
39 Please note, that the parameters `module_load` and `recheck_interval` are only accessible through uci.
40
41 ## UCI Configuration `wifi_schedule`
42 UCI configuration file: `/etc/config/wifi_schedule`:
43
44 ```
45 config global
46         option logging '0'
47         option enabled '0'
48         option recheck_interval '10'
49         option modules_retries '10'
50
51 config entry 'Businesshours'
52         option enabled '0'
53         option daysofweek 'Monday Tuesday Wednesday Thursday Friday'
54         option starttime '06:00'
55         option stoptime '22:00'
56         option forcewifidown '0'
57
58 config entry 'Weekend'
59         option enabled '0'
60         option daysofweek 'Saturday Sunday'
61         option starttime '00:00'
62         option stoptime '00:00'
63         option forcewifidown '1'
64 ```
65
66 ## Script: `wifi_schedule.sh`
67 This is the script that does the work. Make your changes to the UCI config file: `/etc/config/wifi_schedule`
68
69 Then call the script as follows in order to get the necessary cron jobs created:
70
71 `wifi_schedule.sh cron`
72
73 All commands:
74  
75 ```
76 wifi_schedule.sh cron|start|stop|forcestop|recheck|getmodules|savemodules|help
77
78     cron: Create cronjob entries.
79     start: Start wifi.
80     stop: Stop wifi gracefully, i.e. check if there are stations associated and if so keep retrying.
81     forcestop: Stop wifi immediately.
82     recheck: Recheck if wifi can be disabled now.
83     getmodules: Returns a list of modules used by the wireless driver(s)
84     savemodules: Saves a list of automatic determined modules to UCI
85     help: This description.
86 ```