Merge remote-tracking branch 'origin/devel'
[juci.git] / README.md
1 JUCI Webgui for Embedded Routers
2 --------------------------------
3
4 JUCI is a JavaScript-based web interface for broadband routers running iopsys/OpenWRT.
5
6 JUCI is built with html5, angularjs and bootstrap:
7
8 ![Desktop](/media/screenshot.jpg?raw=true "JUCI Screenshot")
9
10 JUCI is theme-able and fully mobile-ready (responsive):
11
12 ![Mobile](/media/mobile.jpg)
13
14 What is JUCI?
15 -------------
16
17 If offers you the following:
18
19 * Extremely resource-efficient for your device - your router only needs to run the core functions (which can be written in C!) and the gui itself is running entirely inside the client's browser). You router only computes and sends the minimum information necessary.
20 * Full mobile support
21 * Easy to work with - the code uses angular.js and html5, making it extremely easy to add new gui elements to the gui.
22 * Full control and flexibility - yet many ready-made components: allowing you to pick yourself which level you want to develop on. There are no restrictions to the look and feel of your gui.
23 * Dynamic theming - you can switch color themes at runtime.
24 * Full language support - allowing for complete localization of your gui. Language file generation is even partially automatic (for html text). Also supporting dynamically changing language on page without having to reload the application. Also featuring quick debug mode for translations where you can see which strings are missing in currently used language pack.
25
26 Usage on OpenWRT
27 ----------------
28
29 You can now try JUCI on openwrt.
30
31 Here is how to install it:
32
33 - Add juci feed to your feeds.conf.default
34 src-git-full juci git@public.inteno.se:juci.git
35
36 - Update and install the feed (with -f to force overrides)
37 ./scripts/feeds update juci
38 ./scripts/feeds install -f -p juci -a
39
40 - select juci core, inteno theme and plugins under JUCI menu in menuconfig
41   (NOTE: some plugins conflict with eachother so you can not select
42   juci-broadcom-wl and juci-openwrt-wireless at the same time).
43
44 For example, you could append this to your .config and then do make defconfig:
45
46         CONFIG_PACKAGE_juci-ubus-core=y
47         # CONFIG_PACKAGE_juci-asterisk is not set
48         # CONFIG_PACKAGE_juci-broadcom-dsl is not set
49         # CONFIG_PACKAGE_juci-broadcom-ethernet is not set
50         # CONFIG_PACKAGE_juci-broadcom-vlan is not set
51         # CONFIG_PACKAGE_juci-broadcom-wl is not set
52         CONFIG_PACKAGE_juci-ddns=y
53         CONFIG_PACKAGE_juci-diagnostics=y
54         CONFIG_PACKAGE_juci-dnsmasq-dhcp=y
55         CONFIG_PACKAGE_juci-dropbear=y
56         CONFIG_PACKAGE_juci-ethernet=y
57         CONFIG_PACKAGE_juci-event=y
58         CONFIG_PACKAGE_juci-firewall-fw3=y
59         # CONFIG_PACKAGE_juci-freecwmp is not set
60         # CONFIG_PACKAGE_juci-igmpinfo is not set
61         # CONFIG_PACKAGE_juci-inteno-multiwan is not set
62         # CONFIG_PACKAGE_juci-inteno-router is not set
63         # CONFIG_PACKAGE_juci-jquery-console=y
64         # CONFIG_PACKAGE_juci-macdb is not set
65         CONFIG_PACKAGE_juci-minidlna=y
66         CONFIG_PACKAGE_juci-mod-status=y
67         CONFIG_PACKAGE_juci-mod-system=y
68         # CONFIG_PACKAGE_juci-natalie-dect is not set
69         # CONFIG_PACKAGE_juci-netmode is not set
70         CONFIG_PACKAGE_juci-network-netifd=y
71         CONFIG_PACKAGE_juci-openwrt-wireless=y
72         # CONFIG_PACKAGE_juci-router-openwrt is not set
73         CONFIG_PACKAGE_juci-samba=y
74         CONFIG_PACKAGE_juci-simple-gui=y
75         CONFIG_PACKAGE_juci-snmp=y
76         CONFIG_PACKAGE_juci-sysupgrade=y
77         CONFIG_PACKAGE_juci-uhttpd=y
78         CONFIG_PACKAGE_juci-upnp=y
79         CONFIG_PACKAGE_juci-usb=y
80         # CONFIG_PACKAGE_juci-utils is not set
81         CONFIG_PACKAGE_juci-theme-inteno=y
82         CONFIG_PACKAGE_juci=y
83
84 - BUILD!
85
86
87 If you go to your router ip you should see the login screen. By default admin
88 user is used to login but if you don't have password set for admin user you
89 will not be able to login. So then go to the console and set password for admin
90 user or change the user used for logging in by editing /etc/config/rpcd and
91 then do /etc/init.d/rpcd restart.
92
93 JUCI also includes a nodejs server which you can do for local testing and for
94 forwarding jsonrpc calls to your router during testing (juci-local-server).
95
96 Good to know
97 ------------
98
99 Addons can be developed on top of juci by creating package that installs js and
100 css files into the router /www folder and then runs juci-update at postinstall
101 (index.html is actually generated automatically).
102
103 In most cases you will never need to modify core juci code. If you need to
104 change behavior of some function, you can always override the public function
105 in javascript without having to modify the original implementation.
106
107 Juci uses modified version of uhttpd that can serve gz files with proper
108 content type based on actual gzipped content.
109
110 JUCI also uses modified versions of ubus and rpcd on openwrt which you can also
111 install from the feed (using -f option).
112
113 Backend Code
114 ------------
115
116 Juci backend mostly consists of scripts that implement ubus functions which
117 become available to the gui code through json rpc. These scripts are simple
118 glue that juci uses to interact with the rest of the system. You can place
119 these scripts in ubus/ folder of your plugin. Each script should have a
120 globally unique name (preferably a name that identifies it as being part of a
121 specific plugin) and it will be placed into /usr/lib/ubus/juci folder on the
122 router.
123
124 All of these scripts are then managed by ubus-scriptd service on the router
125 which makes then available on ubus.
126
127 ubus-scriptd supports both batch scripts and services. Most of juci backend
128 tasks are usually batch scripts that become ubus objects.