How To: Add a new setting

[maehw]

Hi!

I had mentioned in #23 that I was planning to implement a feature:

I've also planned to add a feature where you can decide if pressing the button after having taken a photo a) cancels the print (as it is now) or b) confirms the print (and the printout is not mandatory but optional). But that's completely unrelated and unfinished - I'd keep those changes out of the PR.

I need some help to get started. The first step would be to add a new setting and make it both visible and changeable via the web app.

All I know so far is that the I'd like to add a boolean setting to
https://github.com/xtech/self-o-mat/blob/master/api.proto

E.g.

message BoothSettings {
    required ListSetting language_choice = 5;

    required BoolSetting storage_enabled = 10;
    required BoolSetting printer_enabled = 11;
    optional BoolSetting printer_confirm_print = 12;

Do new settings need to be optional?

What is next? E.g. how do I add a slider to the web app? How do I add captions in different languages, etc.?

Thank you for your support.

[ClemensElflein]

The code is designed in a way that it's quite simple to add a new feature to the app.

You basically don't need to touch the app code at all, since the UI is dynamically generated automatically.

To implement a new setting, you need to do the following (if I remember correctly):

1. Add the setting to the .proto file. This will tell the app to show a control for the setting.
   BoothSettings and CameraSettings correspond to the two tabs in the app.
   Use optional for settings which are not always shown (enable debug, hardware kit only, only when a certain camera is attached,...) or required, if the setting should always be visible.
   Use the following mapping:
   • BoolSetting for a true/false checkbox
   • FloatSetting for a min/max float value
   • IntSetting similar to float, but as int
   • ReadOnlySetting to show a text to the user
   • PostSetting for a "click to perform action" setting (e.g. take picture, adjust focus, ...)
2. (optional) Build the code once in order to regenerate the protobuf code, then the IDE will syntax highlight for you.
3. Then you need to tell the app which text to display to the user and the current value of the setting. This is achieved in this function:

   self-o-mat/src/api/BoothApi.cpp

   Lines 601 to 829 in 514ec38

   	mux.handle("/booth_settings")
   	.get([this](served::response &res, const served::request &req) {
   	BoothSettings currentBoothSettings;
   	boost::property_tree::ptree locale;
   	try {
   	boost::property_tree::read_json("./i18n/" + req.header("lang") + ".json", locale);
   	} catch (boost::exception &e) {
   	boost::property_tree::read_json("./i18n/en.json", locale);
   	}
   	auto controller = logic->getSelfomatController();
   	{
   	auto setting = currentBoothSettings.mutable_language_choice();
   	setting->set_name(locale.get<string>("api.booth.languageChoice"));
   	setting->set_update_url("/booth_settings/language/which");
   	setting->set_currentindex(logic->getLanguageChoice());
   	for(auto &choice : *logic->getLanguageChoices())
   	setting->add_values(choice);
   	}
   	{
   	auto setting = currentBoothSettings.mutable_storage_enabled();
   	setting->set_name(locale.get<string>("api.booth.storageEnabled"));
   	setting->set_update_url("/booth_settings/storage/enabled");
   	setting->set_currentvalue(logic->getStorageEnabled());
   	}
   	{
   	auto setting = currentBoothSettings.mutable_printer_enabled();
   	setting->set_name(locale.get<string>("api.booth.printerEnabled"));
   	setting->set_update_url("/booth_settings/printer/enabled");
   	setting->set_currentvalue(logic->getPrinterEnabled());
   	}
   	{
   	auto setting = currentBoothSettings.mutable_filter_choice();
   	setting->set_name(locale.get<string>("api.booth.filterEnabled"));
   	setting->set_update_url("/booth_settings/filter/which");
   	setting->set_currentindex(logic->getFilterChoice());
   	for(auto &choice : *logic->getFilterChoices())
   	setting->add_values(choice);
   	}
   	{
   	auto setting = currentBoothSettings.mutable_filter_gain();
   	setting->set_name(locale.get<string>("api.booth.filterGain"));
   	setting->set_update_url("/booth_settings/filter/gain");
   	setting->set_currentvalue(logic->getFilterGain());
   	setting->set_minvalue(0.0);
   	setting->set_maxvalue(1.0);
   	}
   	{
   	auto setting = currentBoothSettings.mutable_autofocus_before_trigger();
   	setting->set_name(locale.get<string>("api.booth.autofocus_before_trigger"));
   	setting->set_update_url("/booth_settings/autofocus_before_trigger/enabled");
   	setting->set_currentvalue(logic->getAutofocusBeforeTrigger());
   	}
   	bool flashAvailable = logic->getFlashAvailable();
   	bool flashEnabled = logic->getFlashEnabled();
   	if (flashAvailable) {
   	{
   	auto setting = currentBoothSettings.mutable_flash_enabled();
   	setting->set_name(locale.get<string>("api.booth.flashEnabled"));
   	setting->set_update_url("/booth_settings/flash/enabled");
   	setting->set_currentvalue(flashEnabled);
   	}
   	{
   	auto setting = currentBoothSettings.mutable_flashmode();
   	setting->set_name(locale.get<string>("api.booth.iTTLEnabled"));
   	setting->set_update_url("/booth_settings/flash/ittl/enabled");
   	setting->set_currentvalue(logic->getSelfomatController()->getFlashMode());
   	}
   	{
   	auto setting = currentBoothSettings.mutable_flash_duration_micros();
   	setting->set_update_url("/booth_settings/flash/duration");
   	setting->set_name(locale.get<string>("api.booth.flashDuration"));
   	setting->set_currentvalue(controller->getFlashDurationMicros());
   	setting->set_minvalue(0);
   	setting->set_maxvalue(40000);
   	}
   	{
   	auto setting = currentBoothSettings.mutable_flash_test();
   	setting->set_name(locale.get<string>("api.booth.flashTest"));
   	setting->set_post_url("/flash");
   	}
   	}
   	{
   	auto setting = currentBoothSettings.mutable_template_upload();
   	setting->set_post_url("/template_upload");
   	setting->set_name(locale.get<string>("api.booth.templateUpload"));
   	setting->set_input_accept("image/x-png,image/png");
   	}
   	if (logic->getTemplateLoaded()) {
   	{
   	auto setting = currentBoothSettings.mutable_template_enabled();
   	setting->set_update_url("/booth_settings/template_enabled");
   	setting->set_name(locale.get<string>("api.booth.templateEnabled"));
   	setting->set_currentvalue(logic->getTemplateEnabled());
   	}
   	}
   	if (this->show_led_setup) {
   	{
   	auto setting = currentBoothSettings.mutable_led_mode();
   	setting->set_update_url("/booth_settings/led_mode");
   	setting->set_name(locale.get<string>("api.booth.ledMode"));
   	setting->set_currentindex(controller->getLedType());
   	setting->add_values(SelfomatController::LED_TYPE::RGB.humanName);
   	setting->add_values(SelfomatController::LED_TYPE::RGBW.humanName);
   	}
   	{
   	auto setting = currentBoothSettings.mutable_led_count();
   	setting->set_update_url("/booth_settings/led_count");
   	setting->set_name(locale.get<string>("api.booth.ledCount"));
   	switch (controller->getLedCount()) {
   	case 12:
   	setting->set_currentindex(0);
   	break;
   	case 16:
   	setting->set_currentindex(1);
   	break;
   	case 24:
   	setting->set_currentindex(2);
   	break;
   	case 32:
   	setting->set_currentindex(3);
   	break;
   	default:
   	setting->set_currentindex(0);
   	break;
   	}
   	setting->add_values(SelfomatController::LED_COUNT::COUNT_12.humanName);
   	setting->add_values(SelfomatController::LED_COUNT::COUNT_16.humanName);
   	setting->add_values(SelfomatController::LED_COUNT::COUNT_24.humanName);
   	setting->add_values(SelfomatController::LED_COUNT::COUNT_32.humanName);
   	}
   	}
   	{
   	auto setting = currentBoothSettings.mutable_led_offset_clockwise();
   	setting->set_post_url("/booth_settings/led_offset_cw");
   	setting->set_name(locale.get<string>("api.booth.ledOffset") + " +");
   	}
   	{
   	auto setting = currentBoothSettings.mutable_led_offset_counter_clockwise();
   	setting->set_post_url("/booth_settings/led_offset_ccw");
   	setting->set_name(locale.get<string>("api.booth.ledOffset") + " -");
   	}
   	{
   	auto setting = currentBoothSettings.mutable_countdown_duration();
   	setting->set_update_url("/booth_settings/countdown_duration");
   	setting->set_name(locale.get<string>("api.booth.countdownDuration"));
   	setting->set_currentindex(controller->getCountDownMillis() / 1000 - 1);
   	for (int i = 1; i <= 10; i++) {
   	setting->add_values(std::to_string(i) + "s");
   	}
   	}
   	{
   	auto setting = currentBoothSettings.mutable_max_led_brightness();
   	setting->set_update_url("/booth_settings/max_led_brightness");
   	setting->set_name(locale.get<string>("api.booth.maxLedBrightness"));
   	setting->set_minvalue(20);
   	setting->set_maxvalue(255);
   	setting->set_currentvalue(controller->getMaxLedBrightness());
   	}
   	{
   	auto setting = currentBoothSettings.mutable_update_mode();
   	setting->set_name(locale.get<string>("api.booth.updateMode"));
   	setting->set_post_url("/update");
   	setting->set_alert(locale.get<string>("api.booth.updateAlert"));
   	}
   	{
   	auto setting = currentBoothSettings.mutable_cups_link();
   	setting->set_name(locale.get<string>("api.booth.cupsSetup"));
   	setting->set_url("http://192.168.4.1:631");
   	}
   	{
   	auto setting = currentBoothSettings.mutable_debug_log_enabled();
   	setting->set_update_url("/booth_settings/debug_log_enabled");
   	setting->set_name(locale.get<string>("api.booth.debugLogEnabled"));
   	setting->set_currentvalue(logic->getDebugLogEnabled());
   	}
   	{
   	auto triggerCountSetting = currentBoothSettings.mutable_trigger_counter();
   	triggerCountSetting->set_name(locale.get<string>("api.booth.triggerCounter"));
   	triggerCountSetting->set_value(std::to_string(logic->getTriggerCounter()));
   	}
   	{
   	auto setting = currentBoothSettings.mutable_software_version();
   	setting->set_name(locale.get<string>("api.booth.software_version"));
   	setting->set_value("v1.0.9 - 20200417");
   	}
   	res << currentBoothSettings.SerializeAsString();
   	});

   • Basically you copy/paste the contents of an existing setting and use it as a template.
     • set_name = the title to show to the user. This should be read from the i18n file.
     • set_update_url = the url which the app will POST to as soon as the setting is changed
     • set_currentvalue = the current value of the setting
   • I18N info is found here: https://github.com/xtech/self-o-mat/blob/master/i18n/de.json and here https://github.com/xtech/self-o-mat/blob/master/i18n/en.json
4. Add the update URL which was set in the above step. Same File (BoothApi.cpp, but a POST handler. Just copy and paste an existing setting as example). E.g. for a BoolSetting:

   self-o-mat/src/api/BoothApi.cpp

   Lines 302 to 315 in 514ec38

   	mux.handle("/booth_settings/printer/enabled")
   	.post([this](served::response &res, const served::request &req) {
   	BoolUpdate update;
   	if (!update.ParseFromString(req.body())) {
   	served::response::stock_reply(400, res);
   	return;
   	}
   	logic->setPrinterEnabled(update.value(), true);
   	LOG_I(TAG, "updated printer enabled to: ", std::to_string(update.value()));
   	served::response::stock_reply(200, res);
   	});

This should be all that is needed. If you have any questions, feel free to ask. I hope that I didn't forget anything.

[maehw]

Thanks, Clemens!

That was a good starting point. As my setting affects the BoothLogic:

• Add new private boolean member printConfirmationEnabled in src/logic/BoothLogic.h
• Add new public setter method, e.g. bool getPrintConfirmationEnabled(); (add implementation in src/logic/BoothLogic.cpp, declaration to src/logic/BoothLogic.h)
• Add new public getter method, e.g. void BoothLogic::setPrintConfirmationEnabled(bool printConfirmationEnabled, bool persist) (add implementation in src/logic/BoothLogic.cpp, declaration to src/logic/BoothLogic.h)
• Add logic to the setter & getter implementations 😃
• The following steps are probably optional (only when you want to make the setting changes immediately visible?):
  • Add setter to GUI interface class IGui, e.g. virtual void setPrintConfirmationEnabled(bool printConfirmationEnabled) = 0;
  • Add new private boolean member to interface class
  • Add setter implementation to classes implementing the interface class like BoothGui
• Add new members to initialization lists?

Then building the software again does not seem to be enough:

cd build
cmake ..
make

And restarting the application did not make the setting appear in the web app.

Do you also need to run ./build.sh from /web?

If so, I'd need some further help here, please:

$ ./build.sh 

> self-o-mat@0.0.1 proto
> pbjs -t  static-module ../api.proto -o src/app/protos/api.js && pbts --no-comments src/app/protos/api.js -o src/app/protos/api.d.ts

sh: 1: pbjs: not found
npm ERR! code 127
npm ERR! path /home/pi/self-o-mat/web
npm ERR! command failed
npm ERR! command sh -c pbjs -t  static-module ../api.proto -o src/app/protos/api.js && pbts --no-comments src/app/protos/api.js -o src/app/protos/api.d.ts

npm ERR! A complete log of this run can be found in:
npm ERR!     /home/pi/.npm/_logs/2022-02-21T19_36_13_873Z-debug.log

> self-o-mat@0.0.1 build
> ionic build --prod

sh: 1: ionic: not found
npm ERR! code 127
npm ERR! path /home/pi/self-o-mat/web
npm ERR! command failed
npm ERR! command sh -c ionic build --prod

npm ERR! A complete log of this run can be found in:
npm ERR!     /home/pi/.npm/_logs/2022-02-21T19_36_15_112Z-debug.log

Edit: with the contents of the log file being...

$ cat /home/pi/.npm/_logs/2022-02-21T19_36_15_112Z-debug.log 
0 verbose cli [ '/usr/bin/node', '/usr/bin/npm', 'run', 'build' ]
1 info using npm@7.5.2
2 info using node@v12.22.5
3 timing config:load:defaults Completed in 5ms
4 timing config:load:file:/usr/share/nodejs/npm/npmrc Completed in 6ms
5 timing config:load:builtin Completed in 6ms
6 timing config:load:cli Completed in 6ms
7 timing config:load:env Completed in 1ms
8 timing config:load:file:/home/pi/self-o-mat/web/.npmrc Completed in 1ms
9 timing config:load:project Completed in 3ms
10 timing config:load:file:/home/pi/.npmrc Completed in 1ms
11 timing config:load:user Completed in 1ms
12 timing config:load:file:/etc/npmrc Completed in 0ms
13 timing config:load:global Completed in 0ms
14 timing config:load:cafile Completed in 1ms
15 timing config:load:validate Completed in 1ms
16 timing config:load:setUserAgent Completed in 1ms
17 timing config:load:setEnvs Completed in 3ms
18 timing config:load Completed in 30ms
19 verbose npm-session 93e949abd7f93d0e
20 timing npm:load Completed in 61ms
21 timing command:run-script Completed in 38ms
22 verbose stack Error: command failed
22 verbose stack     at ChildProcess.<anonymous> (/usr/share/nodejs/@npmcli/promise-spawn/index.js:64:27)
22 verbose stack     at ChildProcess.emit (events.js:314:20)
22 verbose stack     at maybeClose (internal/child_process.js:1022:16)
22 verbose stack     at Process.ChildProcess._handle.onexit (internal/child_process.js:287:5)
23 verbose pkgid self-o-mat@0.0.1
24 verbose cwd /home/pi/self-o-mat/web
25 verbose Linux 5.10.92-v7l+
26 verbose argv "/usr/bin/node" "/usr/bin/npm" "run" "build"
27 verbose node v12.22.5
28 verbose npm  v7.5.2
29 error code 127
30 error path /home/pi/self-o-mat/web
31 error command failed
32 error command sh -c ionic build --prod
33 verbose exit 127

[ClemensElflein]

Yes, you are right. We have to rebuild the app in order to include the new setting. The code is generated during building, not during runtime. Sorry, I forgot.

I have tried this in the last hours and am finally able to build the app again. 🎉

It turns out, that the package.json file had some dependencies missing as well as a wrong one..? I'm not sure how this even worked before.

So, hopefully, you should be able to build the app as follows:
0. I have the following versions of node and npm installed:

➜  ~ npm -v
8.4.1
➜  ~ node -v 
v17.5.0

1. Install the ionic cli. It needs to be installed globally.

sudo npm i -g @ionic/cli

2. Install all dependencies. This is done by executing npm install in the web directory:

➜  web git:(tutorial/add_new_setting) npm install

This may complain about deprecated dependencies, but will hopefully install everything you need.
3. You should now be able to build the app by running ./build.sh in the directory.

[ClemensElflein]

Info
So, I am using Ubuntu 20.04 on my development desktop PC for this. I have not tried this directly on the Pi.

Uninstalling node
So for uninstalling, I did the following:

sudo apt remove nodejs
sudo apt purge nodejs
sudo apt autoremove 

Interestingly, npm and node still worked, so I ran the following commands (taken from here: https://stackoverflow.com/questions/32426601/how-can-i-completely-uninstall-nodejs-npm-and-node-in-ubuntu):

sudo rm -rf /usr/local/bin/npm 
sudo rm -rf /usr/local/share/man/man1/node* 
sudo rm -rf /usr/local/lib/dtrace/node.d
rm -rf ~/.npm
rm -rf ~/.node-gyp
sudo rm -rf /opt/local/bin/node
sudo rm -rf /opt/local/include/node
sudo rm -rf /opt/local/lib/node_modules
sudo rm -rf /usr/local/lib/node*
sudo rm -rf /usr/local/include/node*
sudo rm -rf /usr/local/bin/node*

Now trying to run npm or node does not work (command not found).

Reinstalling Node
Then I decided to try the installation using the nvm (https://github.com/nvm-sh/nvm#installing-and-updating). It seems to be the best way to do things and it worked fine for me on the first try:

I ran the following commands:

wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash

Then I needed to open a new terminal, since the nvm command did not work directly.

In the new terminal, it worked:

➜  ~ nvm install node
➜  ~ node -v
v17.6.0
➜  ~ npm -v
8.5.1

So at this point, npm and node worked fine for me.

Now I did the following:

#First, I cd into the web dir
cd /home/clemens/Dev/self-o-mat/web
#Then, I deleted the old node_modules folder (just to be safe that everything will be downloaded again)
rm -rf node_modules/
#Now, I installed ionic-cli (note that even though it's a global install I used **no** sudo here, sudo npm does not work for me)
npm i -g @ionic/cli
#At this point, I was able to run ./build.sh. I did not even need to run npm install, I guess that ionic does this for us? It took some time, so be patient. But the command was successful:
./build.sh
[...]
chunk {89} 89.95dbddcfa71037b21fc1.js () 5.07 kB  [rendered]
chunk {90} 90.e6ed79502c6690cb6c49.js () 569 bytes  [rendered]
chunk {91} 91.20b23744597c843b227f.js () 7.45 kB  [rendered]
chunk {92} 92.8fa2df7f4e37dfbfa32d.js () 7.48 kB  [rendered]
chunk {93} 93.1f05aa0d3a5219e889f4.js () 9.74 kB  [rendered]
chunk {94} 94.a6e43cdaf83c971eb51c.js () 10.3 kB  [rendered]
chunk {95} 95.bceec9d3b0584e950914.js () 7.24 kB  [rendered]
chunk {96} 96.fa6a3191ebb57e79d0e5.js () 7.08 kB  [rendered]
chunk {97} 97.52eb2e34a68b61a2dd55.js () 8.71 kB  [rendered]
chunk {98} 98.72c07c4ffee139062a14.js () 8.86 kB  [rendered]
chunk {99} 99.fef26656a3975dbd6d98.js () 983 bytes  [rendered]
chunk {100} 100.3453b1df54df36ef77a5.js () 4.65 kB  [rendered]
chunk {101} 101.98ab67dd4288bbff029d.js () 77.1 kB  [rendered]
chunk {102} 102.efecb1a5b963467377aa.js () 18 kB  [rendered]

Hope, that this helps you.

[maehw]

Clemens, thank you very much for your patience and your help. I really appreciate it!

This is the first time I really get in touch with node/npm. The last time I've done something with JavaScript was, when you only ran it in your web browser.

Your step-by-step guidance was pretty helpful!

Some remarks (might be interesting for others reading this discussion, not you and me):

• Instead of opening a new terminal, I executed $ source .bashrc
• There was no subfolder node_modules/ inside of the web/ directory on my setup
• There were a lot of upgrade warnings
• During the execution of build.sh I was informed that @angular/cli had not been installed previously and so I agreed to install it
• The build process may take quite a while (several minutes), but it works!

Unfortunately, the setting still does not show on the web app. But I'll keep playing around with that.

[maehw]

Is this probably related to having "multiple apps"?

$ find . -name app
./build/app
./web/node_modules/@ionic/core/dist/types/components/app
./web/node_modules/@ionic/core/dist/collection/components/app
./web/node_modules/@schematics/angular/universal/files/src/app
./web/src/app

The file build_web.sh looks like some script to replace the app. What are the parameters to call it? Or is this just for use in your productive enviromnet?

[ClemensElflein]

I'm glad to hear that the guide helped!
The many warnings are not really a problem, but we should at some point update the dependencies. It's not really a security problem, since the app will not be exposed to the internet anyways. The node_modules folder contains the downloaded dependencies and is ignored by .gitignore. It will be there after your first successful build (but you don't need to delete it every time, I only did it to force npm to download the libraries again).

As soon as the app is rebuilt (using build.sh, it also generates the JS files for the protobuf api), the new setting will be included.
I therefore think that your self-o-mat software still serves an old version of the app.

Basically it is like this:

• the web/ folder contains the sources for the app, the web/www folder contains the compiled version of the app.
• the web/build.sh file replaces the web/www folder with the new app
• as soon as you build the self-o-mat (C++) software, the CMake script copies the contents of the web/www folder to the final assets directory (along with some json files, images, fonts, etc). This copied version of the app will then be served by the self-o-mat app.

Therefore my theory is: Could it be that you have rebuilt the app, but not the self-o-mat software? In this case, the self-o-mat software would still serve the old outdated version of the app. Try cleaning and rebuilding the app.

You could also push your current repository somewhere, then I could take a look if you like.

[maehw]

Yes, thank you. I think needing to rebuilding the self-o-mat (C++) software in addition was one thing.
In addition, I think also got some synchronization issue (using rsync excludes) between the Raspberry Pi and the development PC.
I finally see the setting in the web browser.
Thank you!

[ClemensElflein]

I have created a new branch and implemented the minimal changes needed for a new setting. Note that the app in this branch was not rebuilt, so you can use it to test your setup.

The important changes are: 0726aa0