MMM-ChartProvider-JSON

This magic mirror module is a MMM-ChartProvider module that is part of the MMM-Chartxxx and MMM-Feedxxx interrelated modules.

For an overview of these modules see the README.md in https://github.com/TheBodger/MMM-ChartDisplay.

the -JSON module reads JSON formatted data, from a URL or local text file and formats it into one of more NDTF standard feeds to one or more MMM-ChartDisplay consumers.

Example

Dependencies

This module requires both MMM-FeedUtilities and MMM-ChartUtilies to be installed.

Before installing this module; use https://github.com/TheBodger/MMM-ChartUtilities to setup the MMM-Chart... dependencies and install all modules. use https://github.com/TheBodger/MMM-FeedUtilities to setup the MMM-Feed... dependencies and install all modules.

Installation

To install the module, use your terminal to:

1. Navigate to your MagicMirror's modules folder. If you are using the default installation directory, use the command:
   cd ~/MagicMirror/modules
2. Clone the module:
   git clone https://github.com/TheBodger/MMM-ChartProvider-JSON

Using the module

MagicMirror² Configuration

To use this module, add the following minimum configuration block to the modules array in the config/config.js file:

{
  consumerids:['consumerid of MMM-ChartDisplay],
  id:'unique id of this module instance',
  input: "file name or URL of JSON feed",
  jsonfeeds: [
    {
      setid: "unique setid of this data set",
      subject: "key name in the input to be used as the subject value",
      object: "string denoting the object(ive) of this data set",
      value: "key name in the input to be used as the actual value",  
    },
    
  ]
}

Configuration Options

Option	Details
text	Optional - Possible values: Any string. Default value: The Module name
consumerids	Required - a list of 1 or more consumer modules this module will provide for. Possible values: An array of strings exactly matching the ID of one or more MMM-ChartDisplay modules Default value: none
id	Required - The unique ID of this provider module Possible values: any unique string Default value: none
datarefreshinterval	Optional - milliseconds to pause before checking for new data in the feeds. Possible values: a number in milliseconds Default value: 60000
input	Required - the local filename with file path relative to the Magicmirror folder or the URL of the JSON feed Possible values: any valid file and path or URL Default value: none
jsonfeeds	Required - An array of one or more feed definitions, see below for the jsonfeed configuration options
waitforqueuetime	Ignore - Queue delay between ending one queue item and starting the next Possible values: a number in milliseconds. Default value: 10
JSONFeed Format
feedname	Optional - Name of the feed for reference purposes Possible values: Any unique string. Default value: none
setid	Required - The unique identifier of this set of data produced by this definition. It will be used in the MMM-ChartDisplay configuration to uniquely identify this set. Possible values: Any unique string. Default value: none
rootkey	Optional - the JSON address of the base level of the data to use for extracting data Possible values: Any string representing, in dot notation the JSON that identifies the root level of data to extract. Default value: none - the first level of the JSON Data
oldestage	Optional - Currently unused. Possible values: 'today' or a number of minutes or a valid date(See Moment.js formats. Default value: none
subject	Required - The key name, including any parent levels up to but excluding the rootkey level that will be used to populate the subject field value. Possible values: Any string of a dot notation JSON key address. Default value: none
object	Required - The value that will be used to populate the object field value. Possible values: Any string. Default value: none
value	Required - The key name, including any parent levels up to but excluding the rootkey level that will be used to populate the value field value. Possible values: Any string of a dot notation JSON key address. Default value: none
type	Optional - The format the value will be held in the output feed. if numeric, then the value will be validated as numeric and if it fails the item will be dropped Possible values: 'string' or 'numeric'. Default value: 'string'
timestamp	Optional - The key name, including any parent levels up to but excluding the rootkey level that will be used to populate the timestamp field value or an offset from the runtime of the module as a number of seconds. Possible values: Any string of a dot notation JSON key address or a numeric value of seconds offset (+-). Default value: none - equivalent to 0 second offset
timestampformat	Optional - A moment compatible string indicating the format of the timestamp in the input JSON feed. Possible values: Any valid moment string Default value: none
filename	Optional - The filename, with path, where the output feed will be written in a JSON format Possible values: Any valid filename and path string Default value: none

Example configuration

this configuration produces two feeds from the input JSON feed,

{
  consumerids:['MMCD1'],
  id:'MMCP1',
  input: "https://opendata.ecdc.europa.eu/covid19/casedistribution/json/",
  jsonfeeds: [
    {
      setid: "CV19Pop",
      rootkey: "records",
      subject: "geoId",
      object: "population",
      value: "popData2018",
      filename: "population.json",
    },
    {
       setid:"CV19Dth",
      rootkey: "records",
      subject: "geoId",
      object: "coviddeaths",
      value: "deaths",
      type: "numeric",
      timestamp: "dateRep",
      timestampformat: "DD-MM-YYYY",
    }
  ]
}

Additional Notes

This is a WIP; changes are being made all the time to improve the compatibility across the modules. Please refresh this and the MMM-feedUtilities and MMM-ChartUtilities modules with a git pull in the relevant modules folders.

The JSON input must be well formed and capable of being parsed with JSON.parse(). If there are errors generated whilst trying to parse the JSON, there are plenty of on-line tools that can be used to validate the feed and indicate where the issue may occur.

Look out for the correct key name/value name pairs for output purposes and a format for an input timestamp.