diff --git a/configuration/introduction.md b/configuration/introduction.md index e8fb472b..f8e8d057 100644 --- a/configuration/introduction.md +++ b/configuration/introduction.md @@ -59,6 +59,7 @@ The following properties can be configured, place them above the modules item: | `electronOptions` | An optional array of Electron (browser) options. This allows configuration of e.g. the browser screen size and position (example: `electronOptions: { fullscreen: false, width: 800, height: 600 }`). Kiosk mode can be enabled by setting `kiosk: true`, `autoHideMenuBar: false` and `fullscreen: false`. More options can be found [here](https://github.com/electron/electron/blob/master/docs/api/browser-window.md). This will most likely be used in advanced installations, below. | [] | | `electronSwitches` | An optional array of Electron switches. This allows configuration of electron app itself.
This properties will not affect the `serveronly` mode. Usually normal `MM` users don't need this property, but if you are a hard-core hacker, you might need this to handle Electron itself over `MagicMirror` provides. More options can be found [here](https://www.electronjs.org/docs/latest/api/command-line-switches) (Not all available switches are described there.)
example:`electronSwitches:["enable-transparent-visuals", "disable-gpu"];` | [] | | `customCss` | The path of the `custom.css` stylesheet. The default is `css/custom.css`. | `css/custom.css` | +| `watchTargets` | An optional array of file paths to monitor when using `node --run server:watch`. When any of these files change, the server automatically restarts and connected browsers reload. Particularly useful when frequently modifying `config.js`, `custom.css`, or module files during development or setup. Example: `watchTargets: ["config/config.js", "css/custom.css", "modules/MMM-MyModule/MMM-MyModule.js"]`. See [Development Mode](/core-development/debugging.html#development-mode-with-auto-reload) for more details. | `undefined` | After the above options, you will then add modules. See [module configuration](/modules/configuration.md) for more information. @@ -74,7 +75,7 @@ are: | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | MM_CONFIG_FILE | This specifies an alternate configuration file for the system. This is useful when running multiple mirrors on the same device. This does not work with the template option below. NOTE: this file **_MUST_** be located in a directory within the MagicMirror directory. Ideally, place any config file in the config subdirectory. | | MM_PORT | This specifies an alternate TCP/IP port, overriding "port" item within the config file. This is useful for testing to see if the product will run using another port. | -| mmFetchTimeout | time in milliseconds for fetch timeout. default (30000)

this value can be used to adjust the nodejs fetch function timeout value (default 10 seconds) for all node_helper modules that use fetch() | +| mmFetchTimeout | time in milliseconds for fetch timeout. default (30000)

this value can be used to adjust the nodejs fetch function timeout value for all node_helper modules that use fetch() | #### Examples of use diff --git a/core-development/debugging.md b/core-development/debugging.md index fbe92468..b9f34752 100644 --- a/core-development/debugging.md +++ b/core-development/debugging.md @@ -30,18 +30,57 @@ Developer consoles in browsers and the Electron app (typically CTRL+SHIFT+I to toggle open/close) can be used to set client-side breakpoints, step through scripts and inspect variables. +## Watch Mode with Auto-Reload + +For active development, MagicMirror² provides a `server:watch` script that +automatically restarts the server and reloads connected browsers when files +change: + +```sh +node --run server:watch +``` + +This mode monitors files specified in your `config.js` under the `watchTargets` +property: + +```js +let config = { + watchTargets: [ + "config/config.js", + "css/custom.css", + "modules/MMM-MyModule/MMM-MyModule.js", + "modules/MMM-MyModule/node_helper.js", + ], + // ... rest of config +}; +``` + +When any monitored file changes: + +1. The server automatically restarts +2. Waits for the port to become available +3. Sends a reload notification to all connected browsers via Socket.io +4. Browsers automatically refresh to show the changes + +This creates a seamless development experience where you can edit code, save, +and see the results within seconds without manual restarts. + +**Note:** If `watchTargets` is empty or undefined, the watcher starts but +monitors nothing. + ## Logging While there are no log files produced by the server, info is reported in two different places: -- The console when running from `npm run start` or `npm run server`. +- The console when running from `node --run start`, `node --run server`, or + `node --run server:watch`. - This is separated into two streams, `console.log()` is output as the `stdout` stream, and - `console.error()` is output as the `stderr` stream. - These can be redirected to files when starting the server. `>` will redirect `stdout`, and `2>` will redirect `stderr`. `2>&1` will combine both streams: - `npm run start > out.log 2>&1` + `node --run start > out.log 2>&1` - The browser's developer console (typically CTRL+SHIFT+I to toggle open/close) will have output from scripts that run on the browser. @@ -113,5 +152,5 @@ script, such as `start:dev`: Or when running from the command line (Linux example): ```sh -TZ=Europe/Madrid npm run start:dev +TZ=Europe/Madrid node --run start:dev ``` diff --git a/cspell.config.json b/cspell.config.json index 5beb0f3b..d2520014 100644 --- a/cspell.config.json +++ b/cspell.config.json @@ -64,7 +64,6 @@ "Trixie", "trunc", "tympanus", - "ukmetoffice", "ukmetofficedatahub", "UKMO", "updatenotification", diff --git a/modules/updatenotification.md b/modules/updatenotification.md index 1b4606de..66f44b64 100644 --- a/modules/updatenotification.md +++ b/modules/updatenotification.md @@ -31,7 +31,7 @@ The following properties can be configured: | `updates` | Array of updates modules commands.
**Default value:** `[]` (see bellow) | | `updateTimeout` | Maximum Update duration before cancel it.
**Default Value:** `120000` (2 minutes) | | `updateAutorestart` | Restart automatically MagicMirror² after update is done.
**Default Value:** `false` | -| `useModulesFromConfig` | If `false`, iterate over the modules directory instead of using the modules defined in `config.js`.
**Default Value:** `true` | +| `useModulesFromConfig` | If `false`, iterate over the modules directory instead of using the modules defined in `config.js`.
**Default Value:** `true` | ### `updates` Array diff --git a/modules/weather.md b/modules/weather.md index ebd799c1..9475026f 100755 --- a/modules/weather.md +++ b/modules/weather.md @@ -12,11 +12,11 @@ in stone, so keep that in mind when you want to contribute. ## Screenshot -### Current weather: +### Current weather ![Screenshot of current weather](./screenshots/weather_current.png) -### Forecast: +### Forecast ![Screenshot of weather forecast](./screenshots/weather_forecast.png) @@ -43,7 +43,7 @@ The following properties can be configured: | Option | Description | | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `weatherProvider` | Which weather provider should be used.

**Possible values:** `openweathermap` , `pirateweather` , `weathergov`, `ukmetofficedatahub`, `ukmetoffice`, `weatherbit`, `envcanada`, `openmeteo`, `weatherflow`, `SMHI` or `yr`
**Default value:** `openweathermap` | +| `weatherProvider` | Which weather provider should be used.

**Possible values:** `openweathermap` , `pirateweather` , `weathergov`, `ukmetofficedatahub`, `weatherbit`, `envcanada`, `openmeteo`, `weatherflow`, `SMHI` or `yr`
**Default value:** `openweathermap` | | `type` | Which type of weather data should be displayed.

**Possible values:** `current` , `hourly` , `daily` , or `forecast`
**Default value:** `current`

**Note:** The `daily` type is another name for the `forecast` type, and the two are interchangeable.

The `hourly` type is currently only implemented for these provider:
- **Environment Canada** (`envcanada`)
- **Openmeteo**
- **OpenWeatherMap** (`openweathermap`), and only when `/onecall` is used as the specified endpoint. Latitude and longitude [(see below)](/modules/weather.md#openweathermap-options) are **required** for `hourly`. The locationID and location options are ignored when the OpenWeatherMap One Call API is used and you will get wrong weather information.
- **Weather.gov** (`weathergov`)
- **Yr** (`yr`) | | `units` | What units to use. Specified by config.js

**Possible values:** `config.units` = Specified by config.js, `metric` = Celsius, `imperial` = Fahrenheit
**Default value:** `config.units` | | `tempUnits` | What units to use for temperature. If not specified, the module uses the `units` value from `config.js`.

**Possible values:** `config.units` = Specified by config.js, `metric` = Celsius, `imperial` = Fahrenheit
**Default value:** `config.units` | @@ -56,7 +56,7 @@ The following properties can be configured: | `showPeriod` | Show the period (am/pm) with 12 hour format

**Possible values:** `true` or `false`
**Default value:** `true` | | `showPeriodUpper` | Show the period (AM/PM) with 12 hour format as uppercase

**Possible values:** `true` or `false`
**Default value:** `false` | | `showPrecipitationAmount` | Show the amount of rain/snow.

Not supported by all providers, and some providers do not support all `type`s. Supported providers are `envcanada`, `openmeteo`, `openweathermap`, `smhi`, `weatherbit` and `yr`.

**Possible values:** `true` or `false`
**Default value:** `false` | -| `showPrecipitationProbability` | Show the probability of rain/snow.

Not supported by all providers, and some providers do not support all `type`s. Supported providers are `envcanada`, `openmeteo`, `openweathermap`, `ukmetoffice`, `ukmetofficedatahub`, `weatherbit`, `weatherflow`, `weathergov` and `yr`.

**Possible values:** `true` or `false`
**Default value:** `false` | +| `showPrecipitationProbability` | Show the probability of rain/snow.

Not supported by all providers, and some providers do not support all `type`s. Supported providers are `envcanada`, `openmeteo`, `openweathermap`, `ukmetofficedatahub`, `weatherbit`, `weatherflow`, `weathergov` and `yr`.

**Possible values:** `true` or `false`
**Default value:** `false` | | `showUVIndex` | Show the UV Index.

Not supported by all providers. Implemented provider is `openmeteo` but others could have support.

**Possible values:** `true` or `false`
**Default value:** `false` | | `lang` | The language of the days.

**Possible values:** `en`, `nl`, `ru`, etc ...
**Default value:** uses value of _config.language_ | | `decimalSymbol` | The decimal symbol to use.

**Possible values:** `.`, `,` or any other symbol.
**Default value:** `.` | @@ -81,15 +81,16 @@ The following properties can be configured: #### Weather forecast options -| Option | Description | -| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `tableClass` | The class for the forecast table.

**Possible values:** `'xsmall'`, `'small'`, `'medium'`, `'large'`, `'xlarge'`
**Default value:** `'small'` | -| `colored` | If set to `true`, the min and max temperature are color coded.

**Default value:** `false` | -| `fade` | Fade the future events to black. (Gradient)

**Possible values:** `true` or `false`
**Default value:** `true` | -| `fadePoint` | Where to start fade?

**Possible values:** `0` (top of the list) - `1` (bottom of list)
**Default value:** `0.25` | -| `maxNumberOfDays` | How many days of forecast to return. Specified by config.js

**Possible values:** `1` - `16`
**Default value:** `5` (5 days)
This value is optional. By default the weather module will return 5 days. | -| `maxEntries` | How many entries of an OpenWeatherMap One Call hourly or daily forecast type to return. Specified by config.js

**Possible values:** `1` - `48` for `'hourly'` , `1` - `7` for `'daily'`
**Default value:** `5` (5 entries)
This value is optional and specifically meant to be used with the OpenWeatherMap provider and its `'/onecall'` endpoint. By default the weather module will return 5 entries. Intended to act as a more generalized of the `maxNumberOfDays` option. | -| `ignoreToday` | If set to `true`, today's weather will not be displayed.

**Possible values:** `true` or `false`
**Default value:** `false` | +| Option | Description | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `tableClass` | The class for the forecast table.

**Possible values:** `'xsmall'`, `'small'`, `'medium'`, `'large'`, `'xlarge'`
**Default value:** `'small'` | +| `colored` | If set to `true`, the min and max temperature are color coded.

**Default value:** `false` | +| `fade` | Fade the future events to black. (Gradient)

**Possible values:** `true` or `false`
**Default value:** `true` | +| `fadePoint` | Where to start fade?

**Possible values:** `0` (top of the list) - `1` (bottom of list)
**Default value:** `0.25` | +| `maxNumberOfDays` | How many days of forecast to return. Specified by config.js

**Possible values:** `1` - `16`
**Default value:** `5` (5 days)
This value is optional. By default the weather module will return 5 days. | +| `maxEntries` | How many entries of an OpenWeatherMap One Call hourly or daily forecast type to return. Specified by config.js

**Possible values:** `1` - `48` for `'hourly'` , `1` - `7` for `'daily'`
**Default value:** `5` (5 entries)
This value is optional and specifically meant to be used with the OpenWeatherMap provider and its `'/onecall'` endpoint. By default the weather module will return 5 entries. Intended to act as a more generalized of the `maxNumberOfDays` option. | +| `ignoreToday` | If set to `true`, today's weather will not be displayed.

**Possible values:** `true` or `false`
**Default value:** `false` | +| `forecastDateFormat` | The date format to use for displaying forecast dates. Uses [Moment.js format](https://momentjs.com/docs/#/displaying/format/).

**Possible values:** Any valid Moment.js format string, e.g., `'ddd'` (Mon, Tue), `'dddd'` (Monday, Tuesday), `'D MMM'` (18 Oct), `'DD.MM.'` (18.10.)
**Default value:** `'ddd'`
This option only applies to the forecast view (`type: "forecast"`). | ### OpenWeatherMap options @@ -127,14 +128,6 @@ retrieve more than 5 days you must subscribe to the OpenWeatherMap API. | `lat` | The geo coordinate latitude.

This value is **REQUIRED** | | `lon` | The geo coordinate longitude.

This value is **REQUIRED** | -### UK Met Office (`ukmetoffice`) options - -| Option | Description | -| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `apiBase` | The UKMO base URL.

**Default value:** `'https://datapoint.metoffice.gov.uk/public/data/val/wxfcs/all/json/'` | -| `locationID` | The UKMO API location code.

**Possible values:** `322942`
This value is **REQUIRED** | -| `apiKey` | The [UK Met Office](https://www.metoffice.gov.uk/datapoint/getting-started) API key, which can be obtained by creating an UKMO Datapoint account.

This value is **REQUIRED** | - ### UK Met Office (`ukmetofficedatahub`) options | Option | Description | @@ -176,11 +169,11 @@ nighttime forecast for the current day. When using the `type: "hourly"` config, the module can display a max of 24 hours. -| Option | Description | -| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `siteCode` | The city/town unique identifier for which weather is to be displayed.

**Example:** `siteCode: 's0000458'` is the value for Toronto, Ontario

To determine the `siteCode` value for a Canadian city/town, look at the Environment Canada document at https://dd.weather.gc.ca/citypage_weather/docs/site_list_en.csv (or site_list_fr.csv). There you will find a table with city/town names you can search under column B (English Names), with the corresponding `siteCode` under column A (Codes)

This value is **REQUIRED** | -| `provCode` | The 2-character province code for the selected city/town `siteCode`.

**Example:** `provCode: 'ON'` is the value for Toronto, Ontario

To determine the `provCode` value for a Canadian city/town, look at the Environment Canada document at https://dd.weather.gc.ca/citypage_weather/docs/site_list_en.csv (or site_list_fr.csv). There you will find a table with city/town names you can search under column B (English Names), with the corresponding `provCode` under column C (Province) - and of course the `siteCode` under column A (Codes)

This value is **REQUIRED** | -| `location` | The free-format text string intended to hold a location name (e.g. city) that should appear in the module header.

**Example:** `location: 'Toronto, ON'` | +| Option | Description | +| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `siteCode` | The city/town unique identifier for which weather is to be displayed.

**Example:** `siteCode: 's0000458'` is the value for Toronto, Ontario

To determine the `siteCode` value for a Canadian city/town, look at the Environment Canada document at https://dd.weather.gc.ca/today/citypage_weather/docs/site_list_en.csv (or site_list_fr.csv). There you will find a table with city/town names you can search under column B (English Names), with the corresponding `siteCode` under column A (Codes)

This value is **REQUIRED** | +| `provCode` | The 2-character province code for the selected city/town `siteCode`.

**Example:** `provCode: 'ON'` is the value for Toronto, Ontario

To determine the `provCode` value for a Canadian city/town, look at the Environment Canada document at https://dd.weather.gc.ca/today/citypage_weather/docs/site_list_en.csv (or site_list_fr.csv). There you will find a table with city/town names you can search under column B (English Names), with the corresponding `provCode` under column C (Province) - and of course the `siteCode` under column A (Codes)

This value is **REQUIRED** | +| `location` | The free-format text string intended to hold a location name (e.g. city) that should appear in the module header.

**Example:** `location: 'Toronto, ON'` | ### Weatherflow options