node-red-m2x

Node-RED M2X Node ================= A Node-RED node used to store time-series data in AT&T M2X. This node is also included out-of-the-box with AT&T Flow Designer.

AT&T M2X is a cloud-based fully managed time-series data storage service for network connected machine-to-machine (M2M) devices and the Internet of Things (IoT).

Installation

This node is available as an npm package (https://www.npmjs.com/package/node-red-m2x). Run the following command in the root directory of your Node-RED Directory:

npm install node-red-m2x

Usage

Use node-red-m2x to store time-series data from anything in AT&T M2X and manage your M2X devices.

The user will set the following message properties:

• msg.topic - (required)
• msg.sub_topic - (optional)
• msg.payload - (optional)
• msg.action - (required)
• msg.topic_id - (optional)
• msg.sub_topic_id - (optional)

• msg.topic - The type of object to act on - distribution, device, chart, key.
• msg.action - An action to be applied for this type of object - The second level entry in the below list. (catalog for example)
• msg.payload - A json that represents the body for the rest API, only if such is defiend.
• msg.topic_id - A unique id for either device, distribution, key or chart
• msg.sub_topic_id - Defines the unique instance of sub topic such as distributon's device.

  <ul>
      <li><b>devices</b>
          <ul>
          <li>catalog
              <ul>
                  <li><a href="https://m2x.att.com/developer/documentation/v2/device#List-Search-Public-Devices-Catalog"> Search Catalog </a>
                  <li> msg.payload - catalog parameters
              </ul>
          <li>create
              <ul>
                  <li><a href="https://m2x.att.com/developer/documentation/v2/device#Create-Device"> Create new device </a>
                  <li> msg.payload  - device parameters
              </ul>
          <li>createTrigger
              <ul>
                  <li><a href="https://m2x.att.com/developer/documentation/v2/device#Create-Trigger"> Create a new trigger associated with the specified device.</a>
                  <li> msg.topic_id - The device id
                  <li> msg.payload
              </ul>  
          <li>deleteDevice
              <ul>
                  <li><a href="https://m2x.att.com/developer/documentation/v2/device#Delete-Device"> Delete an existing device</a>
                  <li> msg.topic_id - The device id
              </ul>  
          <li>deleteStream
              <ul>
                  <li><a href="https://m2x.att.com/developer/documentation/v2/device#Delete-Data-Stream"> Delete  a stream</a>
                  <li> msg.topic_id - The device id
                  <li> msg.sub_topic_id - The stream name
              </ul>    
          <li>deleteStreamValues
              <ul>
                  <li><a href="https://m2x.att.com/developer/documentation/v2/device#Delete-Data-Stream-Values"> Delete values from a stream by a date range</a>
                  <li> msg.topic_id - The device id
                  <li> msg.sub_topic_id - The stream name
                  <li> msg.payload - parameters - time range
              </ul>
          <li>deleteTrigger
              <ul>
                  <li><a href="https://m2x.att.com/developer/documentation/v2/device#Delete-Trigger">  Delete an existing trigger associated with a specific device.</a>
                  <li> msg.topic_id - The device id
                  <li> msg.sub_topic_id - The trigger id
              </ul>        
          <li>groups
              <ul>
                  <li><a href="https://m2x.att.com/developer/documentation/v2/device#List-Device-Groups"> List Groups of devices</a>
              </ul>
          <li>keys
              <ul>
                  <li> Returns a list of API keys associated with the device
                  <li> msg.topic_id - The device id
              </ul>  
          <li>list
              <ul>
                  <li><a href="https://m2x.att.com/developer/documentation/v2/device#List-Search-Devices"> List Devices </a>
                  <li> msg.payload - The device id
              </ul>
          <li>location
              <ul>
                  <li><a href="https://m2x.att.com/developer/documentation/v2/device#Read-Device-Location"> View device current location</a>
                  <li> msg.topic_id - The device id
              </ul>  
          <li>log
              <ul>
                  <li><a href="https://m2x.att.com/developer/documentation/v2/device#View-Request-Log"> Return a list of access log to the supplied device</a>
                  <li> msg.topic_id - The device id
              </ul>     
          <li>postMultiple
              <ul>
                  <li><a href="https://m2x.att.com/developer/documentation/v2/device#Post-Device-Updates--Multiple-Values-to-Multiple-Streams-"> Post multiple values to multiple streams</a>
                  <li> msg.topic_id - The device id
                  <li> msg.payload - parameters 
              </ul>    
          <li>postValues
              <ul>
                  <li><a href="https://m2x.att.com/developer/documentation/v2/device#Post-Data-Stream-Values"> Post timestamped values to an existing stream</a>
                  <li> msg.topic_id - The device id
                  <li> msg.sub_topic_id - The stream name
                  <li> msg.payload - parameters - the values - 
                  <pre>[{ "timestamp": "timeStamp" "value": "value" },
  

  { "timestamp": "timeStamp","value": "value>"}]

sampleStreamValues

• Sample values from an existing stream
• msg.topic_id - The device id
• msg.sub_topic_id - The Name of the stream
• msg.payload

setStreamValue

• Set the stream value
• msg.topic_id - The device id
• msg.sub_topic_id - The stream name
• msg.payload - parameters - the values

stream

• View stream details
• msg.topic_id - The device id
• msg.sub_topic_id - The stream name
• msg.payload

streamStats

• Stream Statistics
• msg.topic_id - The device id
• msg.sub_topic_id - The stream name
• msg.payload

streamValues

• List data stream values
• msg.topic_id - The device id
• msg.sub_topic_id - The stream name
• msg.payload

streams

• Return list of associated streams
• msg.topic_id - The device id
• msg.sub_topic_id - The Name of the stream
• msg.payload

testTrigger

• Test the specified trigger by firing it with a fake value.
• msg.topic_id - The device id
• msg.sub_topic_id - The trigger id

trigger

• Get details of a specific trigger associated with an existing device
• msg.topic_id - The device id
• msg.sub_topic_id - The trigger ID

triggers

• Retrieve list of triggers associated with the specified device.
• msg.topic_id - The device id

update

• Update a device
• msg.topic_id - The device id
• msg.payload

updateLocation

• Update a device location
• msg.topic_id - The device id
• msg.payload

updateStream

• Update a data stream
• msg.topic_id - The device id
• msg.sub_topic_id - The Name of the stream
• msg.payload - parameters

updateStreams

• Update a data stream
• msg.topic_id - The device id
• msg.sub_topic_id - Array of streams names
• msg.payload - parameters

updateTrigger

• Update an existing trigger associated with the specified device.
• msg.topic_id - The device id
• msg.sub_topic_id - The trigger name
• msg.payload - trigger parameters

view

• View device
• msg.topic_id - The device id

• distribution
  
  
  • addDevice
    
    • Add a new device to an existing device distribution
    • msg.topic_id - The distribution id
    • msg.sub_topic_id - The device id
    
    
  • create
    • Create a new device distribution
    • msg.payload - Create parameters
  • createTrigger
    • Create a new trigger associated with the distribution
    • msg.topic_id - The distribution id
    • msg.payload - trigger parameters
    
    
  • dataStream
    • View information about a stream associated to the distribution
    • msg.topic_id - The distribution id
    • msg.sub_topic_id - The stream name
  • datatStreams
    • Retrieve a list of data streams associated with the distribution
    • msg.topic_id - The distribution id
    
    
  • deleteDataStream
    • Delete an existing data stream associated to distribution
    • msg.topic_id - The distribution id
    • msg.sub_topic_id - The stream name

                  </ul>        
              <li>deleteDistribution
                  <ul>
                      <li><a href="https://m2x.att.com/developer/documentation/v2/distribution#Delete-Distribution">Delete an existing device distribution</a>
                      <li> msg.topic_id - The distribution id
                  </ul>      
              <li>deleteTrigger
                  <ul>
                      <li><a href="https://m2x.att.com/developer/documentation/v2/distribution#Delete-Trigger">Delete a trigger associated to the distribution</a>
                      <li> msg.topic_id - The distribution id
                      <li> msg.sub_topic_id - The trigger id
                  </ul>     
              <li>devices
                 <ul>
                      <li><a href="https://m2x.att.com/developer/documentation/v2/distribution#List-Devices-from-an-existing-Distribution"> Retrieve a list of devices added to the a device distribution </a>
                      <li> msg.topic_id - The distribution id
                  </ul>    
              <li>list
                  <ul>
                      <li><a href="https://m2x.att.com/developer/documentation/v2/distribution#List-Distributions">Retrieve a list of device distributions </a>
                      <li> msg.payload - List parameters
                  </ul>
              <li>testTrigger
                  <ul>
                      <li><a href="https://m2x.att.com/developer/documentation/v2/distribution#Test-Trigger">Test a trigger by firing a fake value</a>
                      <li> msg.topic_id - The distribution id
                      <li> msg.sub_topic_id - The trigger id
                  </ul>      
              <li>trigger
                  <ul>
                      <li><a href="https://m2x.att.com/developer/documentation/v2/distribution#View-Trigger">Retrieve information about a trigger associated to a distribution</a>
                      <li> msg.topic_id - The distribution id
                      <li> msg.sub_topic_id - The trigger id
                  </ul>       
              <li>triggers
                 <ul>
                      <li><a href="https://m2x.att.com/developer/documentation/v2/distribution#List-Triggers"> Retrieve list of triggers associated with the distribution </a>
                      <li> msg.topic_id - The distribution id
                  </ul>    
              <li>update
                  <ul>
                      <li><a href="https://m2x.att.com/developer/documentation/v2/distribution#Update-Distribution-Details">Update an existing device distribution</a>
                      <li> msg.topic_id - The distribution id
                      <li> msg.payload - distribution parameters 
                  </ul>     
              <li>updateDataStream
                  <ul>
                      <li><a href="https://m2x.att.com/developer/documentation/v2/distribution#Create-Update-Data-Stream">Create/Update a data stream associated with the distribution. </a>
                      <li> msg.topic_id - The distribution id
                      <li> msg.sub_topic_id - The stream name
                      <li> msg.payload - stream parameters 
                  </ul>     
              <li>updateTrigger
                  <ul>
                      <li><a href="https://m2x.att.com/developer/documentation/v2/distribution#Update-Trigger">Update an existing trigger associated with the distribution</a>
                      <li> msg.topic_id - The distribution id
                      <li> msg.sub_topic_id - The trigger id
                      <li> msg.payload - trigger parameters 
                  </ul>        
              <li>view
                   <ul>
                      <li><a href="https://m2x.att.com/developer/documentation/v2/distribution#View-Distribution-Details"> Retrieve information about an existing device distribution </a>
                      <li> msg.topic_id - The disribution id
                  </ul>     
          </ul>   
      </ul>
      <ul>
          <li><b>charts</b>
          <ul>
              <li>create
                  <ul>Get details of a chart
                      <li><a href="https://m2x.att.com/developer/documentation/v2/charts#Create-Chart">Create a new chart</a>
                      <li> msg.payload - chart parameters 
                  </ul>      
              <li>deleteChart
                  <ul>
                      <li><a href="https://m2x.att.com/developer/documentation/v2/charts#Delete-Chart">Delete an existing chart</a>
                      <li> msg.topic_id - The chart id
                  </ul>    
              <li>list
                   <ul>
                      <li><a href="https://m2x.att.com/developer/documentation/v2/charts#List-Charts">Retrieve a list of charts that belongs to the user </a>
                  </ul>       
              <li>render
                  <ul>
                      <li><a href="https://m2x.att.com/developer/documentation/v2/charts#Render-Chart">Retrieve a rendering of a given chart as image format</a>
                      <li>msg.topic_id - The chart id
                      <li>msg.sub_topic_id - the image format : "svg" or "png"
                  </ul>
              <li>update
                    <ul>
                      <li><a href="https://m2x.att.com/developer/documentation/v2/charts#Update-Chart">Update an existing chart</a>
                      <li> msg.topic_id - The chart id
                      <li> msg.payload - chart parameters -<pre>{ series : [{device: "device-id", stream:"stream_name" }]}</pre>
                  </ul>  
              <li>view
                  <ul>
                      <li><a href="https://m2x.att.com/developer/documentation/v2/charts#View-Chart-Details">Get details of a chart</a>
                      <li> msg.topic_id - The chart id
                  </ul>
          </ul>   
      </ul>
      <ul>
          <li><b>keys</b>
          <ul>
              <li>create
                  <ul>
                      <li><a href="https://m2x.att.com/developer/documentation/v2/keys#Create-Key">Create a new API Key</a>
                      <li> msg.payload - key parameters
                  </ul>      
              <li>del
                  <ul>
                      <li><a href="https://m2x.att.com/developer/documentation/v2/charts#Delete-Chart">Delete an existing chart</a>
                      <li> msg.topic_id - The key id
                  </ul>        
              <li>list
                  <ul>
                      <li><a href="https://m2x.att.com/developer/documentation/v2/keys#List-Keys">List all the Master API Keys that belongs to the authenticated user</a>
                  </ul>          
              <li>regenerate
                  <ul>
                      <li><a href="https://m2x.att.com/developer/documentation/v2/keys#Regenerate-Key">Regenerate an API Key token</a>
                      <li> msg.topic_id - The key id
                  </ul>        
              <li>update
                  <ul>
                      <li><a href="https://m2x.att.com/developer/documentation/v2/keys#Update-Key">Update API Key properties</a>
                      <li> msg.topic_id - The key id
                      <li> msg.payload - key parameters
                  </ul>      
              <li>view
                  <ul>
                      <li><a href="https://m2x.att.com/developer/documentation/v2/keys#View-Key-Details">Return the details of the API Key supplied</a>
                      <li> msg.topic_id - The key id
                  </ul>    
          </ul>
      </ul>
      

    Authentication

    There are two ways to pass authentication using the M2X Node:

    • Use the node configuration and set the relevant X-M2X-KEY.
    • Pass the X-M2X-KEY via msg.m2x_key.
    

    Examples

    Create Trigger

    Function Code

    msg.topic = "devices";
    
    msg.action = "createTrigger";
    
    msg.topic_id = "1b2f98cc3b31b527c27ba14fe46c615c";
    
    msg.payload = { "stream": "heat",  
    
      "name": "Hightemperature3",  
    
      "condition": ">", 
    
      "value": 100, 
    
      "callback_url": "http://example.com", 
    
      "status": "enabled",  
    
      "send_location": true }; 
    
        

    <H4> Show device Details<H4>    
    <H5> Function Code </H5>
    <pre>
    msg.topic = "devices";<br>
    msg.action = "view";<br>
    msg.topic_id = "1b2f98cc3b31b527c27ba14fe46c615c";<br>
    return msg;<br>
    </pre>
    </div>
    

    Helpful Resources

    • Signup for an AT&T M2X Account
    • M2X API Documentation
    • Get started with AT&T Flow Designer Account
    • Node-RED Documentation
    • Running Node-Red

    License

    This software is provided under the MIT license. See LICENSE for applicable terms.