Skip to content

Commit a479a54

Browse files
KristjanESPERANTOKristjanESPERANTO
committed
docs: migrate wiki to docs/guide, simplify README
Add comprehensive documentation in docs/guide/: - configuration.md: All config options - monitor-control.md: Wayland, X11, CEC, DPMS, GNOME commands - custom-commands.md: Shell command overrides - custom-menus.md: Custom UI buttons - classes.md: Module grouping - examples.md: Integration with other modules (replaces wiki) - faq.md: Troubleshooting Simplify README: - Remove detailed documentation (now in docs/guide/) - Add Documentation section with links - Replace wiki link with docs/guide/examples.md
1 parent 64e04e3 commit a479a54

File tree

9 files changed

+1035
-32
lines changed

9 files changed

+1035
-32
lines changed

‎README.md‎

Lines changed: 23 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -150,7 +150,7 @@ For example you can use [MMM-ModuleScheduler](https://forum.magicmirror.builders
150150
this.sendNotification("REMOTE_ACTION", { action: "RESTART" });
151151
```
152152
153-
See some specific examples for controlling your mirror from other modules and add your own examples [in the Wiki page here](https://github.com/Jopyth/MMM-Remote-Control/wiki/Examples-for-Controlling-from-Another-Module)
153+
See the [Examples Guide](docs/guide/examples.md) for more integration examples with MMM-ModuleScheduler, MMM-Navigate, Home Assistant, and more.
154154
155155
### List of actions
156156
@@ -249,53 +249,44 @@ Can also be used with the [API](https://documenter.getpostman.com/view/6167403/R
249249
250250
### Using Custom Commands
251251
252-
Depending on your installation, some `shell` commands used by this module are not appropriate and can be overwritten by something that will work for you. To overwrite the commands, add a `customCommand` object to your config section. The following commands are supported:
252+
Override default shell commands for shutdown, reboot, and monitor control. See the [Custom Commands Guide](docs/guide/custom-commands.md) for details.
253253
254-
```js
255-
customCommand: {
256-
shutdownCommand: 'shell command to shutdown your pc',
257-
rebootCommand: 'shell command to reboot your pc',
258-
monitorOnCommand: 'shell command to turn on your monitor',
259-
monitorOffCommand: 'shell command to turn off your monitor',
260-
monitorStatusCommand: 'shell command to return status of monitor, must return either "HDMI" or "true" if screen is on; or "TV is Off" or "false" if it is off to be recognized'
261-
}
262-
```
254+
> **Monitor not turning on/off?** The default `vcgencmd` commands don't work on newer Raspberry Pi OS (Bookworm+). See the [Monitor Control Guide](docs/guide/monitor-control.md) for Wayland, X11, CEC, and other options.
263255
264256
### Custom Classes
265257
266-
You probably wanna hide or show some modules at the same time, right? It's everything that we want this module for, of course.
267-
Well, now you can add as many classes as you like, and define whether they show themselves, hide or toggle between the two stages!
258+
Group modules to show/hide together with a single action. See the [Classes Guide](docs/guide/classes.md) for details.
268259
269260
```js
270261
classes: {
271-
"Any Name You Want": {
272-
hide: ["calendar"],
273-
show: ["newsfeed"],
274-
toggle: ["clock"],
275-
},
276-
"Another Name You Want": {
277-
hide: ["newsfeed"],
278-
show: ["calendar"],
262+
"Day Mode": {
263+
show: ["clock", "weather"],
264+
hide: ["screensaver"],
279265
},
280266
}
281267
```
282268
283269
### Custom Menu Items
284270
285-
You can create your own customized menu items by providing creating a JSON file for the menu and providing a `customMenu: "custom_menu.json"` directive in your config. The file may be called whatever you want, but the name must be provided in the `config` section, and it must be stored in the Mirror's `config/` directory (same place as your `config.js` file).
271+
Create custom buttons in the web interface. See the [Custom Menus Guide](docs/guide/custom-menus.md) for details.
272+
273+
Copy `custom_menu.example.json` to your MagicMirror `config/` folder, rename it, and add to your config:
274+
275+
```js
276+
customMenu: "custom_menu.json",
277+
```
286278
287-
An example menu is provided in this module's folder, titled `custom_menu.example.json`. You can copy this to the `/config` folder and modify as you need.
279+
## Documentation
288280
289-
#### Key Components
281+
For detailed documentation, see the [docs/guide/](docs/guide/) folder:
290282
291-
| Name | Description |
292-
| :------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
293-
| `id` | The HTML id prefix to use for the menu item. |
294-
| `type` | The item type, either `'menu'` or `'item'`. `'menu'` is used to indicate the item is a sub-menu and has an `items` array. `'item'` is used for single menu items and will send a socket "REMOTE_ACTION" notification back to the server. This requires `action:` and `content:` parameters before it can do anything. |
295-
| `text` | The text to display. You can use the translate string `'%%TRANSLATE:YOUR_KEY_HERE%%'`, but remember to also update the appropriate file in `/translations`. |
296-
| `icon` | The [FontAwesome](https://fontawesome.com/v4.7.0/icons/) icon to use (without the leading `-fa`). |
297-
| `items` | An array of sub-menu items to use with `"type":"menu"`. Should be the same format as the top level menu (i.e. the menu structure is recursive). |
298-
| `action` | The `REMOTE_ACTION` notification action name, usually `NOTIFICATION`. Required for `"type":"item"` items to be able to do anything. |
283+
- [Configuration](docs/guide/configuration.md) - All config options
284+
- [Monitor Control](docs/guide/monitor-control.md) - Wayland, X11, CEC commands
285+
- [Custom Commands](docs/guide/custom-commands.md) - Shell command overrides
286+
- [Custom Menus](docs/guide/custom-menus.md) - Build custom UI buttons
287+
- [Classes](docs/guide/classes.md) - Group modules together
288+
- [Examples](docs/guide/examples.md) - Integration with other modules
289+
- [FAQ](docs/guide/faq.md) - Troubleshooting
299290
300291
## Contributing
301292

‎docs/guide/README.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# MMM-Remote-Control Documentation
2+
3+
This guide covers all configuration options and features of MMM-Remote-Control.
4+
5+
## Table of Contents
6+
7+
- [Configuration](configuration.md) - All config options explained
8+
- [Monitor Control](monitor-control.md) - Commands for Wayland, X11, CEC, and more
9+
- [Custom Commands](custom-commands.md) - Create your own shell commands
10+
- [Custom Menus](custom-menus.md) - Build custom menu buttons
11+
- [Classes](classes.md) - Group modules to show/hide together
12+
- [Examples](examples.md) - Integration with other modules
13+
- [FAQ](faq.md) - Frequently Asked Questions
14+
15+
## Quick Links
16+
17+
- [API Documentation](../swagger.json) - REST API reference
18+
- [Main README](../../README.md) - Installation & Quick Start

‎docs/guide/classes.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# Classes
2+
3+
Group modules together to show, hide, or toggle them with a single action.
4+
5+
## Configuration
6+
7+
```js
8+
config: {
9+
classes: {
10+
"Day Mode": {
11+
show: ["clock", "weather", "calendar"],
12+
hide: ["screensaver"],
13+
},
14+
"Night Mode": {
15+
show: ["clock"],
16+
hide: ["weather", "calendar", "newsfeed"],
17+
},
18+
"Toggle News": {
19+
toggle: ["newsfeed"],
20+
},
21+
},
22+
},
23+
```
24+
25+
## Properties
26+
27+
| Property | Description |
28+
| -------- | ------------------------------------------ |
29+
| `show` | Array of module names to show |
30+
| `hide` | Array of module names to hide |
31+
| `toggle` | Array of module names to toggle visibility |
32+
33+
## Usage
34+
35+
### Via Web Interface
36+
37+
Classes appear as buttons in the Remote Control web interface.
38+
39+
### Via API
40+
41+
```bash
42+
curl http://your-mirror:8080/api/classes/Day%20Mode
43+
```
44+
45+
### Via Notification
46+
47+
```js
48+
this.sendNotification("REMOTE_ACTION", {
49+
action: "CLASS",
50+
className: "Day Mode"
51+
});
52+
```
53+
54+
## Examples
55+
56+
### Presentation Mode
57+
58+
Hide everything except a specific module:
59+
60+
```js
61+
classes: {
62+
"Presentation": {
63+
hide: ["clock", "weather", "calendar", "newsfeed"],
64+
show: ["MMM-Slides"],
65+
},
66+
"Normal": {
67+
show: ["clock", "weather", "calendar", "newsfeed"],
68+
hide: ["MMM-Slides"],
69+
},
70+
}
71+
```
72+
73+
### Privacy Mode
74+
75+
Quick toggle for sensitive information:
76+
77+
```js
78+
classes: {
79+
"Privacy": {
80+
hide: ["calendar", "email", "MMM-Todoist"],
81+
},
82+
"Show All": {
83+
show: ["calendar", "email", "MMM-Todoist"],
84+
},
85+
}
86+
```
87+
88+
## Module Names
89+
90+
Use the module name as defined in your `config.js`. For default modules, this is typically lowercase (e.g., `clock`, `weather`, `calendar`). For third-party modules, use the full name (e.g., `MMM-Todoist`).
91+
92+
You can also use the module identifier (e.g., `module_2_calendar`) for more precise control when you have multiple instances of the same module.

‎docs/guide/configuration.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Configuration
2+
3+
All configuration options for MMM-Remote-Control.
4+
5+
## Basic Setup
6+
7+
```js
8+
{
9+
module: 'MMM-Remote-Control',
10+
position: 'bottom_left', // Optional: shows IP address on mirror
11+
config: {
12+
customCommand: {}, // See Custom Commands
13+
showModuleApiMenu: true,
14+
secureEndpoints: true,
15+
// customMenu: "custom_menu.json",
16+
// apiKey: "",
17+
// classes: {}
18+
}
19+
},
20+
```
21+
22+
## Config Options
23+
24+
### showModuleApiMenu
25+
26+
Show the module control menu in the web interface.
27+
28+
```js
29+
config: {
30+
showModuleApiMenu: true,
31+
},
32+
```
33+
34+
### apiKey
35+
36+
Protect your API with an authentication key. See [API Documentation](../../API/README.md) for details.
37+
38+
```js
39+
config: {
40+
apiKey: 'your-secret-api-key',
41+
},
42+
```
43+
44+
### secureEndpoints
45+
46+
When no `apiKey` is set, some dangerous endpoints (shutdown, install modules) are blocked by default. Set to `false` to allow all endpoints without authentication.
47+
48+
```js
49+
config: {
50+
secureEndpoints: true, // Default: true
51+
},
52+
```
53+
54+
### customCommand
55+
56+
Override default shell commands. See [Custom Commands](custom-commands.md) and [Monitor Control](monitor-control.md).
57+
58+
```js
59+
config: {
60+
customCommand: {
61+
shutdownCommand: 'sudo shutdown -h now',
62+
rebootCommand: 'sudo reboot',
63+
monitorOnCommand: 'vcgencmd display_power 1',
64+
monitorOffCommand: 'vcgencmd display_power 0',
65+
monitorStatusCommand: 'vcgencmd display_power -1',
66+
},
67+
},
68+
```
69+
70+
### customMenu
71+
72+
Load a custom menu from a JSON file. See [Custom Menus](custom-menus.md).
73+
74+
```js
75+
config: {
76+
customMenu: "custom_menu.json",
77+
},
78+
```
79+
80+
### classes
81+
82+
Group modules to show/hide together. See [Classes](classes.md).
83+
84+
```js
85+
config: {
86+
classes: {
87+
"Day Mode": {
88+
show: ["clock", "weather"],
89+
hide: ["screensaver"],
90+
},
91+
},
92+
},
93+
```
94+
95+
### pm2ProcessName
96+
97+
If your PM2 process name is not the default `mm`:
98+
99+
```js
100+
config: {
101+
pm2ProcessName: 'MagicMirror',
102+
},
103+
```
104+
105+
## Position
106+
107+
Setting a `position` displays the mirror's IP address on screen. You can hide it later from the module menu.
108+
109+
```js
110+
{
111+
module: 'MMM-Remote-Control',
112+
position: 'bottom_left', // or comment out to hide
113+
config: {}
114+
},
115+
```

‎docs/guide/custom-commands.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Custom Commands
2+
3+
Create your own shell commands to execute on your mirror.
4+
5+
> ⚠️ **Security Warning:** Custom commands execute shell commands on your system. Only add commands you trust.
6+
7+
## Reserved Commands
8+
9+
These commands override the default system commands:
10+
11+
```js
12+
config: {
13+
customCommand: {
14+
shutdownCommand: 'sudo shutdown -h now',
15+
rebootCommand: 'sudo reboot',
16+
monitorOnCommand: 'vcgencmd display_power 1',
17+
monitorOffCommand: 'vcgencmd display_power 0',
18+
monitorStatusCommand: 'vcgencmd display_power -1',
19+
},
20+
},
21+
```
22+
23+
| Command | Description |
24+
| ---------------------- | -------------------------------------------------------- |
25+
| `shutdownCommand` | Shutdown the system |
26+
| `rebootCommand` | Reboot the system |
27+
| `monitorOnCommand` | Turn the display on |
28+
| `monitorOffCommand` | Turn the display off |
29+
| `monitorStatusCommand` | Check display status (must return `"true"` or `"false"`) |
30+
31+
For detailed monitor control options (Wayland, X11, CEC, etc.), see [Monitor Control](monitor-control.md).
32+
33+
## Custom Commands via API
34+
35+
Since v2.3.0, you can define custom commands that can be triggered via the API:
36+
37+
```js
38+
config: {
39+
customCommand: {
40+
myCustomCommand: 'echo "Hello World"',
41+
takeScreenshot: 'scrot /tmp/screenshot.png',
42+
},
43+
},
44+
```
45+
46+
Then call via API:
47+
48+
```bash
49+
curl http://your-mirror:8080/api/command/myCustomCommand
50+
```
51+
52+
## Examples
53+
54+
### Different shutdown for desktop Linux
55+
56+
```js
57+
customCommand: {
58+
shutdownCommand: 'systemctl poweroff',
59+
rebootCommand: 'systemctl reboot',
60+
}
61+
```
62+
63+
### Restart MagicMirror via systemd
64+
65+
```js
66+
customCommand: {
67+
restartCommand: 'sudo systemctl restart magicmirror',
68+
}
69+
```

0 commit comments

Comments
 (0)