Massa Model M3 Wireless Tank Level Sensor and Digi Gateway User’s Guide .
MASSA PRODUCTS CORPORATION Table of Contents Section Page 1.0 Overview and General Operation 1 2.0 Gateway Basic Settings 2 3.0 Operating Modes for Gateway and Sensor - Configuring Sensor - Normal Operation - Diagnostic Mode – Waveforms - Firmware Update - M3 Application Software enable (X4 Gateway only) - Sensor XBee Firmware Update 5 5 11 12 13 13 14 4.
MASSA PRODUCTS CORPORATION 1.0 Overview and General Operation The Massa Model M-3 Wireless Ultrasonic Sensor communicates its tank level information through a Digi International ConnectPort Gateway. This gateway requires set up that is described in this manual. Sensors from the factory are programmed to stay awake and not set up for automated messages. There are several operating modes using the Massa Python code to control the gateway basic functions.
MASSA PRODUCTS CORPORATION 2.0 Gateway Basic Settings 2.2 Time Source Initially you may set up the Time Source by manually entering the time which will be retained up to 10 days when powered off (model X4 gateways only). Go to the System Configuration – Date and Time Settings Web UI and initially, set the time manually. Next, in the Time Source Settings UI, you may select a time source such as my.idigi.com or other reliable time sources. 2.
MASSA PRODUCTS CORPORATION 2.0 Gateway Basic Settings 2.3 Gateway’s XBee Settings (continued from previous page) 2.4 Gateway’s Python Files The files indicated here are required to set up and operate the M3 Sensors. They can be obtained from www.massa.com. The dia.yml file will need to be edited to configure the M3 Sensors to operate with your gateway. See Section 3.0 for more information. The operating files require include: a) python.zip b) zigbee.py c) dia.py d) dia.zip e) dia.
MASSA PRODUCTS CORPORATION 3.0 Operating Modes for Gateway and Sensor There are several operating modes for the gateway using the Massa python driver. The primary function is listening for automated messages from M3 Sensors and sending its data to a cloud or local server. Secondary functions include programming sensor registers, programming XBee registers, obtaining sensor diagnostic data, communicating with the M3 Software application, reprogramming sensor firmware, and reprogramming the XBee radio.
MASSA PRODUCTS CORPORATION 3.0 Operating Modes for Gateway and Sensor 3.1.1 Dia.yml Settings Description - name The setting “name” in the dia.yml file is used to identify the sensor to the device server. A naming suggestion to best help identify a sensor in multiple tanks is to use the sensor model number followed by the sensor’s MAC address or tank number or serial number as indicted. Limit: 32 characters, no quotes. name: M3-150-7A563B40 or M3-150-7A563B40-Tank1 (these are examples) 3.1.2 Dia.
MASSA PRODUCTS CORPORATION 3.0 Operating Modes for Gateway and Sensor 3.1.8 Dia.yml Settings Description – Outgoing Status Message Mode The setting “outgoing_message_mode” in the dia.yml file sets the type of automated outgoing status message format when the sensor wakes up from sleep. See Appendix E for the format of the outgoing message and section 4.0 for an applications example. Leaving this control line out of the dia.
MASSA PRODUCTS CORPORATION 3.0 Operating Modes for Gateway and Sensor 3.1.10 Dia.yml Settings Description – Ultrasonic Signal Sensitivity Setting (continued from previous page) sensitivity Description Very Low This setting should be considered if application has a short maximum sensing range. Low This setting should be considered if application has a short maximum sensing range. Normal This is the default setting to be used in most applications.
MASSA PRODUCTS CORPORATION 3.0 Operating Modes for Gateway and Sensor 3.1.12 Dia.yml Settings Description – User Comment The setting “user_comment” in the dia.yml file allows descriptive information to be programmed into the sensor. Up to 32 ASCII characters can be placed into the sensor. Leaving this control line out of the dia.yml, blank value, or characters other than ASCII will not access this sensor setting. Limits: up to 32 ASCII characters within quotes.
MASSA PRODUCTS CORPORATION 3.0 Operating Modes for Gateway and Sensor 3.1.17 Dia.yml Settings Description – XBee Poll Rate (PO) The setting “poll_rate” in the dia.yml file is used to set the XBee’s Poll Rate (PO) register. Leaving this control line out of the dia.yml, blank value, or incorrectly typed setting value will not access this radio setting. Set this value to 0. poll_rate: 0 3.1.18 Dia.yml Settings Description – XBee Node Discovery Register (NO) The setting “node_discovery” in the dia.
MASSA PRODUCTS CORPORATION 3.0 Operating Modes for Gateway and Sensor 3.1.23 Dia.yml Settings Description – Program Sensor Firmware The setting “program_m3_firmware_file” in the dia.yml file is used upload sensor firmware. The firmware will need to be loaded into the Python manage files memory prior to activation. Leaving this control line out of the dia.yml, blank value, or incorrectly typed filename or incorrect model number within filename will not perform this function.
MASSA PRODUCTS CORPORATION 3.0 Operating Modes for Gateway and Sensor 3.2 Setting up gateway with multiple dia.yml There are several ways to set up how the gateway will operate. One method is to use one dia.yml that is edited and reloaded for the different functions (configuring the sensor, obtaining diagnostics data - waveforms, firmware upload or a listening only mode for automated status messages).
MASSA PRODUCTS CORPORATION 3.0 Operating Modes for Gateway and Sensor 3.2.3 Diagnostic Mode, Obtain Waveforms To obtain diagnostic data that includes ultrasonic waveforms, sensor settings and history buffer up to the last 111 records, set up the command line in the dia.yml as: obtain_diagnostic_data: 'true' This example has its own file named dia_diagnostics.yml and loaded into the Python Files. Enable the Auto-start Settings as shown and boot the gateway.
MASSA PRODUCTS CORPORATION 3.0 Operating Modes for Gateway and Sensor 3.2.4 Sensor Application Firmware Update First, obtain the sensor’s application firmware from Massa Products web site and upload it as shown here stored in the Python Configuration Manage Files location. Firmware versions less than 29.x will also require loading M3BootloaderV3.bin into gateway as seen here. Create a new yml file named dia_m3_firmware_update.
MASSA PRODUCTS CORPORATION 3.0 Operating Modes for Gateway and Sensor 3.2.6 Sensor XBee Firmware Update Follow the steps below to program sensors XBee firmware. You should obtain the firmware from either massa.com or from digi.com. Xbee firrmware has an “ebl” file extension. NOTE: Update only one Sensor XBee firmware at a time. As of this writing, programming the XBee firmware requires several steps. It requires the sensor to keep its XBee ON for the entire programming process.
MASSA PRODUCTS CORPORATION 4.0 Application Setup Example Application Example - Managing a tank farm The M3 Sensors are supplied programmed to stay awake and will commission to any gateway (unless gateway security enabled or child table at max). This will be indicated by the sensor’s red LED blinking every 2 seconds. Typical applications will have the sensors programmed for long sleep periods (1hr, 4hrs, 12hrs or more) to maintain battery life (see Appendix A).
MASSA PRODUCTS CORPORATION 4.0 Application Setup Example (continued from previous page) 7) Go to the iDigi Dia web UI. This will be your gateway address followed by /idigi_dia. See figure to the right. Note: you must have the output drivers in the yml file as shown in Appendix B. An alternative way to obtain status messages is to enable the dia setting log_status: 'true' and view the status_log.txt file stored in the python files web UI.
MASSA PRODUCTS CORPORATION APPENDIX A Miscellaneous Sensor Information Battery Life and Suggested Replacement Voltage Below are the battery life estimates using Energizer L91 batteries with the data acquisition rate programmed to the same time as the wake up time. Wake up and report status rate Battery life at 80% battery efficiency 24 hrs 12 hrs 8 hrs 6 hrs 4 hrs 1 hrs 1 min 3.63 yrs 3.60 yrs 3.58 yrs 3.56 yrs 3.52 yrs 3.17 yrs 4.
MASSA PRODUCTS CORPORATION APPENDIX A (continued from previous page) Miscellaneous Sensor Information LED Behavior Following is the lookup table for the behavior of the LED: LED Behavior OFF RED quick flash every 2 seconds RED quick flash every 2 seconds followed by an extended OFF period Description No power, battery voltage too low, or sensor sleeping if powered Sensor is joined with a ZigBee network, if stays in this mode, then Deep Sleep = 0.
MASSA PRODUCTS CORPORATION APPENDIX A (continued from previous page) Miscellaneous Sensor Information Threshold Settings Defined in Sensor Registers (see section 3.1.10 and 3.1.
MASSA PRODUCTS CORPORATION APPENDIX B Format for dia.yml The controls for the gateway operating mode are found in the dia.yml file which is processed by the Massa Python driver (m3_driver.py). See an example below. It is very important that the syntax is maintained with same spaces and no tabs as shown in this example. It is suggested that you download “Notepad ++” and set it up properly so that any tabs are converted to spaces.
MASSA PRODUCTS CORPORATION APPENDIX C Digi Gateway & Massa M3 Sensor Placement Strategies If you had been previously evaluating this kit in your lab environment, it is now time to move the gateway in a permanent location that will give the best possible wireless performance. Typically, the tank will be in a fixed location, so it will be necessary to place the gateway in a location where you will get the most reliable RF performance between sensor and gateway.
MASSA PRODUCTS CORPORATION APPENDIX C (continued) Digi Gateway & Massa M3 Sensor Placement Strategies This example shows a much taller tank with a gateway placed high overhead. Here the tractor trailer does not impede the radio signals. In this scenario, a chain link fence is between sensor and gateway. A metal fence will significantly reduce the radio range. It is better to place the tank with sensor on the other side of the fence or place a router in a location possibly over the fence.
MASSA PRODUCTS CORPORATION APPENDIX D Fresnel zone and effects on it (see Digi web site for more info) It makes sense that obstructions between a transmitter and receiver will reduce the communication range. In order to obtain the absolute maximum communication range possible, a radio modem system must be installed such that true RF Line-ofSight (LOS) conditions exist between the transmitting and receiving antennas. RF LOS is different that visual LOS.
MASSA PRODUCTS CORPORATION APPENDIX E Outgoing Auto-Message Message Format This is the automated outgoing message format when the sensor wakes up from Deep Sleep. The auto_message_length setting will be the same number indicated in the “EventsToRetrieve” byte. This setting allows you to reduce the size of this message by reducing the amount of records for such reasons as limiting the size for cell plan costs.
MASSA PRODUCTS CORPORATION APPENDIX F M3 Application Software – Understanding an Ultrasonic Waveform This very important tool will allow diagnosing more difficult applications and also allows recording the tanks ultrasonic profile for archival purposes. When the dia.yml configures obtain_diagnostic_data_enable: 'false', waveforms and other data are stored in the gateway. Save the file from the gateway to your PC and use the M3 Application software (see www.massa.com) to recall each waveform.
MASSA PRODUCTS CORPORATION APPENDIX G Checklist for Reliable Sensor and Gateway Operation □ Sensor XBee firmware version 29A0, PO=0, CR=3. Scan channel (SC) set to 0x1ffe. a) PAN ID = 0 for fixed sensor applications that don’t ever expect another gateway in the vicinity or for roving sensors that need to associate with any gateway. b) PAN ID = non-zero for fixed sensor applications that do expect, or have another gateway in the vicinity, in which the sensor is associated is to a specific gateway.
MASSA PRODUCTS CORPORATION APPENDIX H Troubleshooting Guide Issue Condition Solution or work around Missing data, sensor lost association. - Gateway power cycle could lose association. - Gateway Xbee version less than version 21A0. - Poor RF link - Xbee firmware was updated - Upgrade sensor firmware to at least version 31 which will detect unassociated state and attempt to rejoin gateway. - Upgrade gateway Xbee firmware to version 21A0. Sensor Xbee 29A0. - Consider the use of a wall router.
