Merge branch 'doc/mod' into next

27 files changed, 274 insertions, 15 deletions

diff --git a/README.md b/README.md
index 9d4d858..a3da7e7 100644
--- a/README.md
+++ b/README.md
@@ -224,6 +224,11 @@ Available modules
 
 * [Manage ports in bridge](doc/mod/bridge-port-to.md)
 * [Manage VLANs on bridge ports](doc/mod/bridge-port-vlan.md)
+* [Inspect variables](doc/mod/inspectvar.md)
+* [IP address calculation](doc/mod/ipcalc.md)
+* [Send notifications via Matrix](doc/mod/notification-matrix.md)
+* [Send notifications via Telegram](doc/mod/notification-telegram.md)
+* [Download script and run it once](doc/mod/scriptrunonce.md)
 
 Contact
 -------
diff --git a/doc/backup-cloud.md b/doc/backup-cloud.md
index 4df14fd..0761982 100644
--- a/doc/backup-cloud.md
+++ b/doc/backup-cloud.md
@@ -30,7 +30,9 @@ The configuration goes to `global-config-overlay`, these are the parameters:
 * `BackupPassword`: password to encrypt the backup with
 * `BackupRandomDelay`: delay up to amount of seconds when run from scheduler
 
-Also notification settings are required for e-mail, matrix and/or telegram.
+Also notification settings are required for e-mail,
+[matrix](mod/notification-matrix.md) and/or
+[telegram](mod/notification-telegram.md).
 
 Usage and invocation
 --------------------
diff --git a/doc/backup-upload.md b/doc/backup-upload.md
index 1e17d62..72781ba 100644
--- a/doc/backup-upload.md
+++ b/doc/backup-upload.md
@@ -36,7 +36,9 @@ The configuration goes to `global-config-overlay`, these are the parameters:
 * `BackupUploadUser`: username for server authentication
 * `BackupUploadPass`: password for server authentication
 
-Also notification settings are required for e-mail, matrix and/or telegram.
+Also notification settings are required for e-mail,
+[matrix](mod/notification-matrix.md) and/or
+[telegram](mod/notification-telegram.md).
 
 ### Issues with SFTP client
 
diff --git a/doc/check-certificates.md b/doc/check-certificates.md
index f6a4d22..a553e6a 100644
--- a/doc/check-certificates.md
+++ b/doc/check-certificates.md
@@ -27,7 +27,8 @@ Configuration
 -------------
 
 The expiry notifications just require notification settings for e-mail,
-matrix and/or telegram.
+[matrix](mod/notification-matrix.md) and/or
+[telegram](mod/notification-telegram.md).
 
 For automatic download and renewal of certificates you need configuration
 in `global-config-overlay`, these are the parameters:
diff --git a/doc/check-health.md b/doc/check-health.md
index 778c080..f6900ce 100644
--- a/doc/check-health.md
+++ b/doc/check-health.md
@@ -56,7 +56,9 @@ The configuration goes to `global-config-overlay`, these are the parameters:
 * `CheckHealthVoltageLow`: value (in volt*10) giving a hard lower limit
 * `CheckHealthVoltagePercent`: percentage value to trigger voltage jumps
 
-Also notification settings are required for e-mail, matrix and/or telegram.
+Also notification settings are required for e-mail,
+[matrix](mod/notification-matrix.md) and/or
+[telegram](mod/notification-telegram.md).
 
 ---
 [◀ Go back to main README](../README.md)  
diff --git a/doc/check-lte-firmware-upgrade.md b/doc/check-lte-firmware-upgrade.md
index a9da4a2..704a86b 100644
--- a/doc/check-lte-firmware-upgrade.md
+++ b/doc/check-lte-firmware-upgrade.md
@@ -35,7 +35,9 @@ Just install the script:
 Configuration
 -------------
 
-Notification setting are required for e-mail, matrix and/or telegram.
+Notification setting are required for e-mail,
+[matrix](mod/notification-matrix.md) and/or
+[telegram](mod/notification-telegram.md).
 
 See also
 --------
diff --git a/doc/check-routeros-update.md b/doc/check-routeros-update.md
index da74639..cac1850 100644
--- a/doc/check-routeros-update.md
+++ b/doc/check-routeros-update.md
@@ -47,7 +47,9 @@ safe versions from a web server. The configuration goes to
 * `SafeUpdateUrl`: url to check for safe update, the channel (`long-term`,
 `stable` or `testing`) is appended
 
-Also notification settings are required for e-mail, matrix and/or telegram.
+Also notification settings are required for e-mail,
+[matrix](mod/notification-matrix.md) and/or
+[telegram](mod/notification-telegram.md).
 
 Usage and invocation
 --------------------
diff --git a/doc/collect-wireless-mac.md b/doc/collect-wireless-mac.md
index 3120749..5425f76 100644
--- a/doc/collect-wireless-mac.md
+++ b/doc/collect-wireless-mac.md
@@ -40,7 +40,9 @@ On first run a disabled access list entry acting as marker (with comment
 "`--- collected above ---`") is added. Move this entry to define where new
 entries are to be added.
 
-Also notification settings are required for e-mail, matrix and/or telegram.
+Also notification settings are required for e-mail,
+[matrix](mod/notification-matrix.md) and/or
+[telegram](mod/notification-telegram.md).
 
 Usage and invocation
 --------------------
diff --git a/doc/daily-psk.md b/doc/daily-psk.md
index 28baac0..d204691 100644
--- a/doc/daily-psk.md
+++ b/doc/daily-psk.md
@@ -51,7 +51,9 @@ Then add an access list entry:
 
     / interface wireless access-list add comment="Daily PSK" interface=wl-daily private-pre-shared-key="ToBeChangedDaily";
 
-Also notification settings are required for e-mail, matrix and/or telegram.
+Also notification settings are required for e-mail,
+[matrix](mod/notification-matrix.md) and/or
+[telegram](mod/notification-telegram.md).
 
 ---
 [◀ Go back to main README](../README.md)  
diff --git a/doc/log-forward.md b/doc/log-forward.md
index 3a0f3be..1ac6a04 100644
--- a/doc/log-forward.md
+++ b/doc/log-forward.md
@@ -46,7 +46,9 @@ The configuration goes to `global-config-overlay`, these are the parameters:
 * `LogForwardIncludeMessage`: define message text to be forwarded (even if
   filter matches)
 
-Also notification settings are required for e-mail, matrix and/or telegram.
+Also notification settings are required for e-mail,
+[matrix](mod/notification-matrix.md) and/or
+[telegram](mod/notification-telegram.md)m.
 
 ---
 [◀ Go back to main README](../README.md)  
diff --git a/doc/mod/inspectvar.d/inspectvar.avif b/doc/mod/inspectvar.d/inspectvar.avif
new file mode 100644
index 0000000..d4a745f
--- /dev/null
+++ b/doc/mod/inspectvar.d/inspectvar.avif
diff --git a/doc/mod/inspectvar.md b/doc/mod/inspectvar.md
new file mode 100644
index 0000000..d3fb3b2
--- /dev/null
+++ b/doc/mod/inspectvar.md
@@ -0,0 +1,33 @@
+Inspect variables
+=================
+
+[◀ Go back to main README](../../README.md)
+
+> ℹ️️ **Info**: This module can not be used on its own but requires the base
+> installation. See [main README](../../README.md) for details.
+
+Description
+-----------
+
+RouterOS handles not just scalar variables, but also arrays - even nested.
+This module adds a function to inspect variables.
+
+Requirements and installation
+-----------------------------
+
+Just install the module:
+
+    $ScriptInstallUpdate mod/inspectvar;
+
+Usage and invocation
+--------------------
+
+Call the function `$InspectVar` with a variable as parameter:
+
+    $InspectVar $ModeButton
+
+![InspectVar](inspectvar.d/inspectvar.avif)
+
+---
+[◀ Go back to main README](../../README.md)  
+[▲ Go back to top](#top)
diff --git a/doc/mod/ipcalc.d/ipcalc.avif b/doc/mod/ipcalc.d/ipcalc.avif
new file mode 100644
index 0000000..022f325
--- /dev/null
+++ b/doc/mod/ipcalc.d/ipcalc.avif
diff --git a/doc/mod/ipcalc.d/ipcalcreturn.avif b/doc/mod/ipcalc.d/ipcalcreturn.avif
new file mode 100644
index 0000000..d858bb1
--- /dev/null
+++ b/doc/mod/ipcalc.d/ipcalcreturn.avif
diff --git a/doc/mod/ipcalc.md b/doc/mod/ipcalc.md
new file mode 100644
index 0000000..a3e7fc8
--- /dev/null
+++ b/doc/mod/ipcalc.md
@@ -0,0 +1,53 @@
+IP address calculation
+======================
+
+[◀ Go back to main README](../../README.md)
+
+> ℹ️️ **Info**: This module can not be used on its own but requires the base
+> installation. See [main README](../../README.md) for details.
+
+Description
+-----------
+
+This module adds functions for IP address calculation.
+
+Requirements and installation
+-----------------------------
+
+Just install the module:
+
+    $ScriptInstallUpdate mod/ipcalc;
+
+Usage and invocation
+--------------------
+
+### IPCalc
+
+The function `$IPCalc` prints information to terminal, including:
+
+* address
+* netmask
+* network in CIDR notation
+* minimum host address
+* maximum host address
+* broadcast address
+
+It expects an IP address in CIDR notation as argument.
+
+    $IPCalc 192.168.88.1/24;
+
+![IPCalc](ipcalc.d/ipcalc.avif)
+
+### IPCalcReturn
+
+The function `$IPCalcReturn` expects an IP address in CIDR notation as
+argument as well. But it does not print to terminal, instead it returns
+the information in a named array.
+
+    :put ([ $IPCalcReturn  192.168.88.1/24 ]->"broadcast");
+
+![IPCalcReturn](ipcalc.d/ipcalcreturn.avif)
+
+---
+[◀ Go back to main README](../../README.md)  
+[▲ Go back to top](#top)
diff --git a/doc/mod/notification-matrix.md b/doc/mod/notification-matrix.md
new file mode 100644
index 0000000..e357b5b
--- /dev/null
+++ b/doc/mod/notification-matrix.md
@@ -0,0 +1,45 @@
+Send notifications via Matrix
+=============================
+
+[◀ Go back to main README](../../README.md)
+
+> ℹ️️ **Info**: This module can not be used on its own but requires the base
+> installation. See [main README](../../README.md) for details.
+
+Description
+-----------
+
+This module adds support for sending notifications via
+[Matrix](https://matrix.org/) via client server api. A queue is used to
+make sure notifications are not lost on failure but sent later.
+
+Requirements and installation
+-----------------------------
+
+Just install the module:
+
+    $ScriptInstallUpdate mod/notification-matrix;
+
+Also install a Matrix client on at least one of your mobile and/or desktop
+devices and create an account.
+
+Configuration
+-------------
+
+Edit `global-config-overlay`, add `MatrixHomeServer`, `MatrixAccessToken` and
+`MatrixRoom`. Then reload the configuration.
+
+Usage and invocation
+--------------------
+
+There's nothing special to do. Every script or function sending a notification
+will now send it to your Matrix account.
+
+See also
+--------
+
+* [Send notifications via Telegram](notification-telegram.md)
+
+---
+[◀ Go back to main README](../../README.md)  
+[▲ Go back to top](#top)
diff --git a/doc/mod/notification-telegram.d/newbot.avif b/doc/mod/notification-telegram.d/newbot.avif
new file mode 100644
index 0000000..1fc7355
--- /dev/null
+++ b/doc/mod/notification-telegram.d/newbot.avif
diff --git a/doc/mod/notification-telegram.md b/doc/mod/notification-telegram.md
new file mode 100644
index 0000000..435694e
--- /dev/null
+++ b/doc/mod/notification-telegram.md
@@ -0,0 +1,63 @@
+Send notifications via Telegram
+===============================
+
+[◀ Go back to main README](../../README.md)
+
+> ℹ️️ **Info**: This module can not be used on its own but requires the base
+> installation. See [main README](../../README.md) for details.
+
+Description
+-----------
+
+This module adds support for sending notifications via
+[Telegram](https://telegram.org/) via bot api. A queue is used to make sure
+notifications are not lost on failure but sent later.
+
+Requirements and installation
+-----------------------------
+
+Just install the module:
+
+    $ScriptInstallUpdate mod/notification-telegram;
+
+Also install Telegram on at least one of your mobile and/or desktop devices
+and create an account.
+
+Configuration
+-------------
+
+Open Telegram, then start a chat with [BotFather](https://t.me/BotFather) and
+create your own bot:
+
+![create new bot](notification-telegram.d/newbot.avif)
+
+Now open a chat with your bot and start it by clicking the `START` button.
+
+Open just another chat with [GetIDs Bot](https://t.me/getidsbot), again start
+with the `START` button. It will send you some information, including the
+`id`, just below `You`.
+
+Finally edit `global-config-overlay`, add `TelegramTokenId` with the token
+from *BotFather* and `TelegramChatId` with your id from *GetIDs Bot*. Then
+reload the configuration.
+
+### Notifications to a group
+
+Sending notifications to a group is possible as well. Add your bot and the
+*GetIDs Bot* to a group, then use the group's id (which starts with a dash)
+for `TelegramChatId`. Then remove *GetIDs Bot* from group.
+
+Usage and invocation
+--------------------
+
+There's nothing special to do. Every script or function sending a notification
+will now send it to your Telegram account.
+
+See also
+--------
+
+* [Send notifications via Matrix](notification-matrix.md)
+
+---
+[◀ Go back to main README](../../README.md)  
+[▲ Go back to top](#top)
diff --git a/doc/mod/scriptrunonce.d/hello-world.rsc b/doc/mod/scriptrunonce.d/hello-world.rsc
new file mode 100644
index 0000000..17ec575
--- /dev/null
+++ b/doc/mod/scriptrunonce.d/hello-world.rsc
@@ -0,0 +1,3 @@
+#!rsc by RouterOS
+
+:put ("Hello World from " . [ / system identity get name ] . "!");
diff --git a/doc/mod/scriptrunonce.d/scriptrunonce.avif b/doc/mod/scriptrunonce.d/scriptrunonce.avif
new file mode 100644
index 0000000..614c72c
--- /dev/null
+++ b/doc/mod/scriptrunonce.d/scriptrunonce.avif
diff --git a/doc/mod/scriptrunonce.md b/doc/mod/scriptrunonce.md
new file mode 100644
index 0000000..190ed03
--- /dev/null
+++ b/doc/mod/scriptrunonce.md
@@ -0,0 +1,35 @@
+Download script and run it once
+===============================
+
+[◀ Go back to main README](../../README.md)
+
+> ℹ️️ **Info**: This module can not be used on its own but requires the base
+> installation. See [main README](../../README.md) for details.
+
+Description
+-----------
+
+This module adds a function that downloads a script, checks for syntax
+validity and runs it once.
+
+Requirements and installation
+-----------------------------
+
+Just install the module:
+
+    $ScriptInstallUpdate mod/scriptrunonce;
+
+Usage and invocation
+--------------------
+
+The function `$ScriptRunOnce` expects an url pointing to a script as parameter.
+
+    $ScriptRunOnce https://git.eworm.de/cgit/routeros-scripts/plain/doc/mod/scriptrunonce.d/hello-world.rsc
+
+![ScriptRunOnce](scriptrunonce.d/scriptrunonce.avif)
+
+Giving multiple scripts is possible, separated by comma.
+
+---
+[◀ Go back to main README](../../README.md)  
+[▲ Go back to top](#top)
diff --git a/doc/netwatch-notify.md b/doc/netwatch-notify.md
index c9917cb..b2f6dd0 100644
--- a/doc/netwatch-notify.md
+++ b/doc/netwatch-notify.md
@@ -88,7 +88,9 @@ powered off, but accessibility is of interest.
 
 Go and get your coffee ☕️ before sending the print job.
 
-Also notification settings are required for e-mail, matrix and/or telegram.
+Also notification settings are required for e-mail,
+[matrix](mod/notification-matrix.md) and/or
+[telegram](mod/notification-telegram.md).
 
 Tips & Tricks
 -------------
diff --git a/doc/sms-forward.md b/doc/sms-forward.md
index 417f462..9ebae69 100644
--- a/doc/sms-forward.md
+++ b/doc/sms-forward.md
@@ -31,8 +31,10 @@ Just install the script:
 Configuration
 -------------
 
-Notification settings are required for e-mail, matrix and/or telegram. Also
-you have to enable receiving of SMS:
+Notification settings are required for e-mail,
+[matrix](mod/notification-matrix.md) and/or
+[telegram](mod/notification-telegram.md). Also you have to enable receiving
+of SMS:
 
     / tool sms set receive-enabled=yes;
 
diff --git a/global-config b/global-config
index 50e7f54..3ae4557 100644
--- a/global-config
+++ b/global-config
@@ -8,7 +8,7 @@
 
 # Make sure all configuration properties are up to date and this
 # value is in sync with value in script 'global-functions'!
-:global GlobalConfigVersion 77;
+:global GlobalConfigVersion 78;
 
 # This is used for DNS and backup file.
 :global Domain "example.com";
diff --git a/global-config-overlay b/global-config-overlay
index d8c2e0a..7d0c83d 100644
--- a/global-config-overlay
+++ b/global-config-overlay
@@ -8,7 +8,7 @@
 # Make sure all configuration properties are up to date and this
 # value is in sync with value in script 'global-functions'!
 # Comment or remove to disable news and change notifications.
-:global GlobalConfigVersion 77;
+:global GlobalConfigVersion 78;
 
 # Copy configuration from global-config here and modify it.
 
diff --git a/global-config.changes b/global-config.changes
index 727b259..7e029be 100644
--- a/global-config.changes
+++ b/global-config.changes
@@ -86,6 +86,7 @@
         ("Still running RouterOS v6, so last reminder to see https://git.eworm.de/cgit/routeros-scripts/about/#changes-for-routeros-v6") ]);
   76="Added an option to suppress notifications on host down with 'netwatch-notify'.";
   77="Introduced new script 'firmware-upgrade-reboot'. Handle with care!";
+  78="New documentation is online for notifications via Telegram & Matrix, variable inspection, ip address calculation and running scripts once.";
 };
 
 # Migration steps to be applied on script updates
diff --git a/global-functions b/global-functions
index 3323f36..2b37bea 100644
--- a/global-functions
+++ b/global-functions
@@ -8,7 +8,7 @@
 # https://git.eworm.de/cgit/routeros-scripts/about/
 
 # expected configuration version
-:global ExpectedConfigVersion 77;
+:global ExpectedConfigVersion 78;
 
 # global variables not to be changed by user
 :global GlobalFunctionsReady false;