# SULU-CE

SULU is a ReactJS based USP controller, for more details please check sulu [documentation](https://dev.iopsys.eu/websdk/sulu/-/blob/devel/README.md). This directory contains the recipes to build sulu for IOWRT.

There are two ways to include SULU in iowrt, by

1. Adding a pre-build sulu distribution with all the plugins
2. Compile sulu at the iowrt build time, which then include all the selected plugins

Align with above two ways, SULU has two variants

1. sulu - This package usages the pre-built distribution, so it faster but only include iopsys default sulu plugins
2. sulu-builder - This package builds the sulu along with selected plugins from sources, so user can include their sulu-plugins

# Directory structure

This directory contains iowrt sulu plugins packages along with sulu builder.

- sulu-builder - Offers sulu and sulu-builder iowrt packages
- sulu-base - Sulu core source, needed for sulu-builder
- sulu-theme-genexis - Sulu genexis theme plugin, can be used with sulu-builder

# Packages

- Select 'CONFIG_PACKAGE_sulu=y' to use pre-build sulu distribution binaries, OR
- Select 'CONFIG_PACKAGE_sulu-builder=y' to build sulu along with customized plugins from their source code, this is the preferred way if user wants to include/exclude more/default plugins in sulu.
- CONFIG_PACKAGE_sulu-theme-genexis=y, Provides Genexis theme, should only be used with sulu-builder

# How to select a sulu plugins

While building sulu from source, user has to select the all plugins they want to include in sulu, which can be done with 'make menuconfig', below are the list of sulu plugins available currently.

```bash
# CONFIG_PACKAGE_sulu-theme-genexis is not set
```

# How to add a new sulu plugin

User can also add there own sulu plugins as package with a simple makefile as below:

```bash
include $(TOPDIR)/rules.mk
PKG_NAME:=<Name of plugin>
PKG_VERSION:=<Plugin version number>

PKG_SOURCE_PROTO:=git
PKG_SOURCE_URL:=<Plugin url>
PKG_SOURCE_VERSION:=<Plugin version hash to use>
PKG_MIRROR_HASH:=skip

include ../sulu-builder/sulu.mk

# call BuildPackage - OpenWrt buildroot signature
```

# How to add a new sulu plugin with additional install requirements

Sometimes it is required to install additional config files along with the package, to do so such sulu plugins need to have below syntax in Makefile

```bash
include $(TOPDIR)/rules.mk
PKG_NAME:=sulu-lcm
PKG_VERSION:=2.0.0

PKG_SOURCE_PROTO:=git
PKG_SOURCE_URL:=https://dev.iopsys.eu/websdk/sulu-lcm.git
PKG_SOURCE_VERSION:=b3f6028fd168e58b93ae56f616e96712849c656a
PKG_MIRROR_HASH:=skip

SULU_PLUGIN_INSTALL:=1

define Package/$(PKG_NAME)/install
	$(INSTALL_DIR) $(1)/<install_path>
	$(CP) $(PKG_BUILD_DIR)/<source_path>/lcm-store.json $(1)/<install_path>/
endef

include ../sulu-builder/sulu.mk


# call BuildPackage - OpenWrt buildroot signature
```

In the above example Makefile, if user need to install any plugin specific component, that can be added inside 'Package/$(PKG_NAME)/install' definition.

After adding the makefile, user need to specify the list of plugins in below config option, so that sulu-builder selects them and build them along with it.

```bash
CONFIG_SULU_BUILDER_EXTRA_PACKAGES="sulu-plugin1 sulu-plugin2 sulu-theme1"
```

# How to create a new Sulu user with Role Based Access Controller

Sulu has a predefined set of users, but if it is required to add user with more/less datamodel access rights, that can be done from a USP Controller(sulu etc) or by using the command line tool.

In the below example, I use command line tool, but same operations can be done from controller as well to configure it, so we need

- New user
- New user role
- Changes in UserInterface Instance to use the new user role
- A ControllerTrust role to define datamodel access aligned with user role
- Update the sulu controller to use the above role

Some global variables before proceeding further

```bash
export UNAME=testuser
export UPASS=testuser123
```

## Create an User Role

```bash
ROLE="$(obuspa -c add Device.Users.Role. |cut -d " " -f 2)"

obuspa -c set ${ROLE}.RoleName ${UNAME}
obuspa -c set ${ROLE}.Enable 1
```

## Create an User

```bash
USER="$(obuspa -c add Device.Users.User. |cut -d " " -f 2)"

obuspa -c set ${USER}.Username ${UNAME}
obuspa -c set ${USER}.Password ${UPASS}
obuspa -c set ${USER}.RoleParticipation ${ROLE}
obuspa -c set ${USER}.Enable 1
```

## Update UserInterface to use the new UserRole

Sulu has a reload hook to setup the necessary obuspa/mosquitto configuration, so no need to do LocalAgent Controller/MTP setup, this will reload obuspa service after uci update, so we have to wait for service to come up.

```bash
bbfdmd -c set Device.UserInterface.HTTPAccess.1.AllowedRoles "Device.Users.Role.1,${ROLE}"

sleep 30
```

## Create a ControllerTrust role aligned with user role

In this example, full access of 'Device.' added for the new user

```bash
CTROLE="$(obuspa -c add Device.LocalAgent.ControllerTrust.Role. | cut -d " " -f 2)"

PERM="$(obuspa -c add ${CTROLE}.Permission. |cut -d " " -f 2)"

obuspa -c set ${PERM}.Targets Device.
obuspa -c set ${PERM}.Param rw-n
obuspa -c set ${PERM}.Obj rw-n
obuspa -c set ${PERM}.InstantiatedObj rw-n
obuspa -c set ${PERM}.CommandEvent r-xn
obuspa -c set ${PERM}.Enable 1
obuspa -c set ${CTROLE}.Enable 1
```

## Set new role to Controller

```bash
obuspa -c set Device.LocalAgent.Controller.[EndpointID==self::sulu-${UNAME}].AssignedRole "${CTROLE}"
```

After these configuration reboot the device

```bash
reboot
```

After device boots sulu should be able to login with newly added user.

## Make sulu the default UI

If you want SULU to be hosted on port 443 instead of 8443, just select the config option

```bash
CONFIG_SULU_DEFAULT_UI=y
```

or

```bash
CONFIG_SULU_BUILDER_DEFAULT_UI=y
```
