Skip to content

Commit

Permalink
Update Readme
Browse files Browse the repository at this point in the history
  • Loading branch information
Jan Litzenburger authored and Jan Litzenburger committed May 24, 2020
1 parent bf641b7 commit 27ee45c
Showing 1 changed file with 90 additions and 45 deletions.
135 changes: 90 additions & 45 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,77 +1,122 @@
# MMM-RAIN-MAP (Beta)
# MMM-RAIN-MAP

A Rain Radar Map for [Magic Mirror](https://magicmirror.builders/) based on the [Rainviewer API](https://github.com/rainviewer/rainviewer-api-example).
Click here for the [Forum Thread](https://forum.magicmirror.builders/topic/12808/mmm-rain-map).

This is another Rain Radar Map for [Magic Mirror](https://magicmirror.builders/).
It is inspired by [MMM-RAIN-RADAR by jojoduquartier](https://github.com/jojoduquartier/MMM-RAIN-RADAR) but uses [Rainviewer API example](https://github.com/rainviewer/rainviewer-api-example) instead of an iframe.
Click here for the Magic Mirror [Forum Thread](https://forum.magicmirror.builders/topic/12808/mmm-rain-map)

## Features

- Shows Rainviewer.com rain data on OpenStreet Map or Google Maps.
- Shows Rainviewer.com rain data on OpenStreetMap or Google Maps
- Option to support multiple, alternating zoom levels
- Option to only show on rain (dependency to currentweather module)
- Option to add markers on map

## Installing the Module

Navigate to the MagicMirror subfolder "modules" and execute the following command
`git clone https://github.com/jalibu/MMM-RAIN-MAP.git`

## Google API Key

Obtain an api at [Google Developer's page](https://developers.google.com/maps/documentation/javascript/).
* Navigate to the MagicMirror subfolder "modules" and execute the following command
```sh
git clone https://github.com/jalibu/MMM-RAIN-MAP.git
```
* Add the module in the `config/config.js` file:

## Usage
### Sample configuration (OpenStreetMap)

To use this module, add it to the modules array in the `config/config.js` file:
```javascript
{
module: "MMM-RAIN-MAP",
position: "top_left",
config: {
animationSpeed: 600,
displayClockSymbol: true,
displayTime: true,
extraDelayLastFrame: 2000,
height: "420px",
lat: 50,
lng: 8.27,
map: "OSM",
markers: [
{ lat: 50, lng: 8.27, color: "red" },
{ lat: 49.411, lng: 8.715, color: "blue" }
],
onlyOnRain: false,
opacity: 0.65,
timeFormat: "24",
updateIntervalInSeconds: 300,
width: "420px",
zoom: 8,
zoomOutEach: 0,
zoomOutLevel: 2,
}
}
```

### Sample
### Sample configuration (Google Maps)

```javascript
{
module: "MMM-RAIN-MAP",
position: "top_left",
config: {
animationSpeed: 600,
backgroundColor: "rgba(0, 0, 0, 0)",
displayClockSymbol: true,
displayTime: true,
extraDelayLastFrame: 2000,
height: "420px",
width: "420px",
map: "GOOGLE",
key: "<INSERT_HERE>",
lat: 50,
lng: 8.27,
map: "GOOGLE",
mapTypeId: "terrain",
markers: [{ lat: 50, lng: 8.27, color: "red" }],
onlyOnRain: true,
opacity: 0.75,
showClockSymbol: false,
markers: [
{ lat: 50, lng: 8.27 },
{ lat: 49.411, lng: 8.715 }
],
onlyOnRain: false,
opacity: 0.65,
timeFormat: "24",
updateIntervalInSeconds: 300,
width: "420px",
zoom: 8,
zoomOutEach: 2,
zoomOutEach: 0,
zoomOutLevel: 2,
}
}
```

### Options

| Option | Description |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `map` | Map API (Possible values: `GOOGLE` or `OSM` (OpenStreet Map)) <br><br>**Type:** `string` (pixels) <br> **Default value:** `OSM` |
| `key` | _Required if Google_ Google Maps API Key key. |
| `lat` | _Required_ Latitude used to center the map.<br><br>**Type:** `float` |
| `lng` | _Required_ Longitude used to center the map.<br><br>**Type:** `float` |
| `height` | Height of the map. <br><br>**Type:** `string` (pixels) <br> **Default value:** `420px` |
| `width` | Width of the map. <br><br>**Type:** `string` (pixels) <br> **Default value:** `420px` |
| `zoom` | Zoom value to display from lat/lng. <br><br>**Type:** `integer` <br> **Default value:** `8` |
| `mapTypeId` | [Google Maps Only] The map type to display (roadmap, satellite, hybrid, terrain). <br><br>**Type:** `string` <br> **Default value:** `terrain` | |
| `disableDefaultUI` | [Google Maps Only] Disable default UI buttons (Zoom and Street View). <br><br>**Type:** `boolean` <br> **Default value:** `true` |
| `markers` | Additional markers in the map as an array. See example. Note: The color property only works with OpenStreetMap. |
| `backgroundColor` | [Google Maps Only] Backgound behind the map.Can be set to transparent (`'hsla(0, 0%, 0%, 0)'`) or left at black (default). <br><br>**Type:** `string` <br> **Default value:** `'rgba(0, 0, 0, 0)'` |
| `updateIntervalInSeconds` | Update interval for fetching new radar frames in seconds. (New frames are released every 10 minutes) <br><br>**Type:** `int` <br> **Default value:** `300` |
| `animationSpeed` | Determines how fast the frames are played (time per frame in milliseconds). <br><br>**Type:** `int` <br> **Default value:** `600` |
| `extraDelayLastFrame` | Add an extra delay the last frame to stop the animation with the current radar overlay (time in milliseconds)<br><br>**Type:** `int` <br> **Default value:** `2000` |
| `opacity` | Opacity of radar overlay on map. <br><br>**Type:** `float` <br> **Default value:** `0.6` |
| `onlyOnRain` | If set to true, the map is only shown when currentweather module shows rain or show icon. <br><br>**Type:** `boolean` <br> **Default value:** `false` |
| `displayTime` | Show time for each frame. <br><br>**Type:** `boolean` <br> **Default value:** `true` |
| `displayClockSymbol` | Show clock symbol before the time. <br><br>**Type:** `boolean` <br> **Default value:** `true` |
| `zoomOutEach` | If set to a number higher than 0, the map zooms out after n rotations of frames. It zooms back to default zoom level after the same number of rotations.<br><br>**Type:** `int` <br> **Default value:** `0` |
| `zoomOutLevel` | If zoomOutEach is higher 0, this setting determines how far the map zooms out.<br><br>**Type:** `int` <br> **Default value:** `3` |
## Options
### General options

| Option | Description |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `map` | Used Map API <br>Possible values: `'GOOGLE'` or `'OSM'` <br><br>**Type:** `string` <br> **Default value:** `'OSM'` |
| `lat` | __Required:__ Latitude used to center the map.<br><br>**Type:** `float` |
| `lng` | __Required:__ Longitude used to center the map.<br><br>**Type:** `float` |
| `height` | Height of the map. <br><br>**Type:** `string` (pixels) <br> **Default value:** `'420px'` |
| `width` | Width of the map. <br><br>**Type:** `string` (pixels) <br> **Default value:** `'420px'` |
| `zoom` | Map zoom value. <br><br>**Type:** `integer` <br> **Default value:** `8` |
| `markers` | Set markers in the map.<br> Example: `markers:[{lat:50, lng:8.27, color:"red"},{lat:49.411, lng:8.715, color:"blue"}]`<br>Possible colors: `'black','blue','gold','green','grey','orange','red','violet','yellow'`<br> Note: The color property only works with OpenStreetMap.<br><br>**Type:** `array[Object]` <br> **Default value:** `[]` |
| `updateIntervalInSeconds` | Update interval for fetching new radar frames. (New frames are released every 10 minutes) <br><br>**Type:** `int` <br> **Default value:** `300` (time in seconds) |
| `animationSpeed` | Determines how fast the frames are played. <br><br>**Type:** `int` <br> **Default value:** `600` (time per frame in milliseconds) |
| `extraDelayLastFrame` | Add an extra delay to pause the animation on the latest frame.<br><br>**Type:** `int` <br> **Default value:** `2000` (time in milliseconds) |
| `opacity` | Opacity of radar overlay on map. <br><br>**Type:** `float` <br> **Default value:** `0.6` |
| `onlyOnRain` | If set to true, the map is only displayed when `currentweather module` shows rain or snow icon. <br><br>**Type:** `boolean` <br> **Default value:** `false` |
| `displayTime` | Display the time for each frame. <br><br>**Type:** `boolean` <br> **Default value:** `true` |
| `displayClockSymbol` | Display clock symbol as time prefix. <br><br>**Type:** `boolean` <br> **Default value:** `true` |
| `zoomOutEach` | If set to a number higher than 0, the map zooms out after n rotations of frames. It zooms back to default zoom level after the same number of rotations.<br><br>**Type:** `int` <br> **Default value:** `0` (disabled) |
| `zoomOutLevel` | If zoomOutEach is higher 0, this setting determines how far the map zooms out.<br><br>**Type:** `int` <br> **Default value:** `3` |

### Google Maps only options

| Option | Description |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key` | API key for Google Maps. Get a key at [Google Developer's page](https://developers.google.com/maps/documentation/javascript/).<br><br>**Type:** `string` <br> **Default value:** `''` |
| `backgroundColor` | Backgound behind the map. <br>Can be set to transparent (`'hsla(0, 0%, 0%, 0)'`) or left at black (default). <br><br>**Type:** `string` <br> **Default value:** `'rgba(0, 0, 0, 0)'` |
| `disableDefaultUI` | Disable default UI buttons (Zoom and Street View). <br><br>**Type:** `boolean` <br> **Default value:** `true` |
| `mapTypeId` | The map type to display.<br>Possible values: `'roadmap', 'satellite', 'hybrid', 'terrain'`. <br><br>**Type:** `string` <br> **Default value:** `'terrain'` |



## Thanks to
- All testers for their feedback
- [MMM-RAIN-RADAR by jojoduquartier](https://github.com/jojoduquartier/MMM-RAIN-RADAR) for inspiration

0 comments on commit 27ee45c

Please sign in to comment.