Class OneWireContainer21

  • All Implemented Interfaces:
    ClockContainer, OneWireSensor, TemperatureContainer

    public class OneWireContainer21
    extends OneWireContainer
    implements TemperatureContainer, ClockContainer

    1-Wire® container for a Thermochron iButton, DS1921. This container encapsulates the functionality of the 1-Wire family type 21 (hex).

    Features

    • Logs up to 2048 consecutive temperature measurements in nonvolatile, read-only memory
    • Real-Time clock with programmable alarm
    • Programmable high and low temperature alarms
    • Alarm violation times and durations recorded in nonvolatile, read-only memory
    • Automatically 'wakes up' and logs temperature at user-programmable intervals
    • 4096 bits of general-purpose read/write nonvolatile memory
    • 256-bit scratchpad ensures integrity of data transfer
    • On-chip 16-bit CRC generator to verify read operations
    • Long-term histogram with 2@htmlonly °C @endhtmlonly resolution

    Memory

    The memory can be accessed through the objects that are returned from the getMemoryBanks method.

    The following is a list of the MemoryBank instances that are returned:
    • Scratchpad with CRC
      • Implements MemoryBank, PagedMemoryBank
      • Size 32 starting at physical address 0
      • Features Read/Write not-general-purpose volatile
      • Pages 1 page of length 32 bytes
      • Page Features page-device-CRC
      • Extra information for each page Target address, offset, length 3
    • Main Memory
      • Implements MemoryBank, PagedMemoryBank
      • Size 512 starting at physical address 0
      • Features Read/Write general-purpose non-volatile
      • Pages 16 pages of length 32 bytes giving 29 bytes Packet data payload
      • Page Features page-device-CRC
    • Register control
      • Implements MemoryBank, PagedMemoryBank
      • Size 32 starting at physical address 512
      • Features Read/Write not-general-purpose non-volatile
      • Pages 1 pages of length 32 bytes
      • Page Features page-device-CRC
    • Alarm time stamps
      • Implements MemoryBank, PagedMemoryBank
      • Size 96 starting at physical address 544
      • Features Read-only not-general-purpose non-volatile
      • Pages 3 pages of length 32 bytes
      • Page Features page-device-CRC
    • Temperature histogram
      • Implements MemoryBank, PagedMemoryBank
      • Size 128 starting at physical address 2048
      • Features Read-only not-general-purpose non-volatile
      • Pages 4 pages of length 32 bytes
      • Page Features page-device-CRC
    • Temperature log
      • Implements MemoryBank, PagedMemoryBank
      • Size 2048 starting at physical address 4096
      • Features Read-only not-general-purpose non-volatile
      • Pages 64 pages of length 32 bytes
      • Page Features page-device-CRC

    Usage

    The code below starts a mission with the following characteristics:

    • Rollover flag enabled. This means if more than 2048 samples are taken, the newer samples overwrite the oldest samples in the temperature log.
    • High alarm of 28.0@htmlonly °C @endhtmlonly and a low alarm of 23.0@htmlonly °C @endhtmlonly. If the alarm is violated, the Temperature Alarm log will record when and for how long the violation occurred.
    • The clock alarm enabled to Mondays at 12:30:45 pm.
    • Sets the Thermocron's Real-Time Clock to the host system's clock.
    • The mission will start in 2 minutes.
    • A sample rate of 1 minute.
    This code also ensures that the Thermocron's clock is set to run, and that the clock alarm is enabled.

     
           // "ID" is a byte array of size 8 with an address of a part we
           // have already found with family code 12 hex
           // "access" is a DSPortAdapter
           OneWireContainer21 ds1921 = (OneWireContainer21) access.getDeviceContainer(ID);
           ds1921.setupContainer(access,ID);
           //  ds1921 previously setup as a OneWireContainer21
           ds1921.clearMemory();
           //  read the current state of the device
           byte[] state = ds1921.readDevice();
           //  enable rollover
           ds1921.setFlag(ds1921.CONTROL_REGISTER, ds1921.ROLLOVER_ENABLE_FLAG, true, state);
           //  set the high temperature alarm to 28 C
           ds1921.setTemperatureAlarm(ds1921.ALARM_HIGH, 28.0, state);
           //  set the low temperature alarm to 23 C
           ds1921.setTemperatureAlarm(ds1921.ALARM_LOW, 23.0, state);
           //  set the clock alarm to occur weekly, Mondays at 12:30:45 pm
           ds1921.setClockAlarm(12, 30, 45, 2, ds1921.ONCE_PER_WEEK, state);
           //  set the real time clock to the system's current clock
           ds1921.setClock(System.currentTimeMillis(), state);
           //  set the mission to start in 2 minutes
           ds1921.setMissionStartDelay(2,state);
           //  make sure the clock is set to run
           ds1921.setClockRunEnable(true, state);
           //  make sure the clock alarm is enabled
           ds1921.setClockAlarmEnable(true, state);
           //  write all that information out
           ds1921.writeDevice(state);
           //  now enable the mission with a sample rate of 1 minute
           ds1921.enableMission(1);
     
     

    The following code processes the temperature log:

           byte[] state = ds1921.readDevice();
           byte[] log = ds1921.getTemperatureLog(state);
           Calendar time_stamp = ds1921.getMissionTimeStamp(state);
           long time = time_stamp.getTime().getTime() + ds1921.getFirstLogOffset(state);
           int sample_rate = ds1921.getSampleRate(state);
    
           System.out.println("TEMPERATURE LOG");
    
           for (int i=0;i < log.length;i++)
           {
               System.out.println("- Temperature recorded at  : "+(new Date(time)));
               System.out.println("-                     was  : "+ds1921.decodeTemperature(log[i])+" C");
               time += sample_rate * 60 * 1000;
           }
     

    The following code processes the alarm histories:

           byte[] high_history = ds1921.getAlarmHistory(ds1921.TEMPERATURE_HIGH_ALARM);
           byte[] low_history = ds1921.getAlarmHistory(ds1921.TEMPERATURE_LOW_ALARM);
           int sample_rate = ds1921.getSampleRate(state);
           int start_offset, violation_count;
           System.out.println("ALARM HISTORY");
           if (low_history.length==0)
           {
               System.out.println("- No violations against the low temperature alarm.");
               System.out.println("-");
           }
           for (int i=0;i < low_history.length/4; i++)
           {
               start_offset = (low_history [i * 4] & 0x0ff)
                         | ((low_history [i * 4 + 1] << 8) & 0x0ff00)
                         | ((low_history [i * 4 + 2] << 16) & 0x0ff0000);
               violation_count = 0x0ff & low_history[i*4+3];
               System.out.println("- Low alarm started at     : "+(start_offset * sample_rate));
               System.out.println("-                          : Lasted "+(violation_count * sample_rate)+" minutes");
           }
           if (high_history.length==0)
           {
               System.out.println("- No violations against the high temperature alarm.");
               System.out.println("-");
           }
           for (int i=0;i < high_history.length/4; i++)
           {
               start_offset = (high_history [i * 4] & 0x0ff)
                         | ((high_history [i * 4 + 1] << 8) & 0x0ff00)
                         | ((high_history [i * 4 + 2] << 16) & 0x0ff0000);
               violation_count = 0x0ff & high_history[i*4+3];
               System.out.println("- High alarm started at    : "+(start_offset * sample_rate));
               System.out.println("-                          : Lasted "+(violation_count * sample_rate)+" minutes");
           }
     

    The following code processes the temperature histogram:

           double resolution = ds1921.getTemperatureResolution();
           double histBinWidth = ds1921.getHistogramBinWidth();
           double start = ds1921.getHistogramLowTemperature();
           System.out.println("TEMPERATURE HISTOGRAM");
           for (int i=0;i < histogram.length;i++)
           {
              System.out.println("- Histogram entry          : "
                                 + histogram [i] + " at temperature "
                                 + start + " to "
                                 + ( start + (histBinWidth - resolution)) + " C");
              start += histBinWidth;
           }
     

    Also see the usage examples in the TemperatureContainer and ClockContainer interfaces.

    For examples regarding memory operations,

    DataSheet

    http://pdfserv.maxim-ic.com/arpdf/DS1921L-F5X.pdf
    Also visit http://www.ibutton.com/ibuttons/thermochron.html for links to more sources on the DS1921 Thermocron.
    See Also:
    OneWireSensor, SwitchContainer, TemperatureContainer
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int CONTROL_REGISTER
      Address of the control register.
      static byte MEMORY_CLEAR_ENABLE_FLAG
      CONTROL REGISTER FLAG: Must be enabled to allow a clear memory function.
      static byte MEMORY_CLEARED_FLAG
      STATUS REGISTER FLAG: Will read back true if the memory has been cleared.
      static byte MISSION_ENABLE_FLAG
      CONTROL REGISTER FLAG: When DISABLED, the mission will start as soon as the sample rate is written.
      static byte MISSION_IN_PROGRESS_FLAG
      STATUS REGISTER FLAG: Will read back true when a mission is in progress.
      static byte ONCE_PER_DAY
      Alarm frequency setting for the setClockAlarm() method.
      static byte ONCE_PER_HOUR
      Alarm frequency setting for the setClockAlarm() method.
      static byte ONCE_PER_MINUTE
      Alarm frequency setting for the setClockAlarm() method.
      static byte ONCE_PER_SECOND
      Alarm frequency setting for the setClockAlarm() method.
      static byte ONCE_PER_WEEK
      Alarm frequency setting for the setClockAlarm() method.
      static byte OSCILLATOR_ENABLE_FLAG
      CONTROL REGISTER FLAG: When DISABLED, the real time clock will start working.
      static byte ROLLOVER_ENABLE_FLAG
      CONTROL REGISTER FLAG: When enabled, the device will begin overwriting the earlier temperature measurements when the temperature log memory becomes full.
      static byte SAMPLE_IN_PROGRESS_FLAG
      STATUS REGISTER FLAG: Will read back true when a mission temperature conversion is in progress
      static int STATUS_REGISTER
      Address of the status register.
      static byte TEMP_CORE_BUSY_FLAG
      STATUS REGISTER FLAG: Will read back true if a temperature conversion of any kind is in progress.
      static byte TEMP_HIGH_SEARCH_FLAG
      CONTROL REGISTER FLAG: When enabled, the device will respond to conditional search command if the temperature has reached the high temperature threshold.
      static byte TEMP_LOW_SEARCH_FLAG
      CONTROL REGISTER FLAG: When enabled, the device will respond to conditional search command if the temperature has reached the low temperature threshold.
      static byte TEMPERATURE_HIGH_ALARM
      High temperature alarm value for the methods getAlarmStatus(), getAlarmHistory(), and setTemperatureAlarm().
      static byte TEMPERATURE_HIGH_FLAG
      STATUS REGISTER FLAG: Will read back true when the temperature during a mission reaches or exceeds the temperature high threshold.
      static byte TEMPERATURE_LOW_ALARM
      Low temperature alarm value for the methods getAlarmStatus(), getAlarmHistory(), and setTemperatureAlarm().
      static byte TEMPERATURE_LOW_FLAG
      STATUS REGISTER FLAG: Will read back true when a temperature equal to or below the low temperature threshold was detected on a mission.
      static byte TIMER_ALARM
      Clock alarm value for the methods getAlarmStatus() and isClockAlarming().
      static byte TIMER_ALARM_FLAG
      STATUS REGISTER FLAG: Will read back true when a clock alarm has occurred.
      static byte TIMER_ALARM_SEARCH_FLAG
      CONTROL REGISTER FLAG: When enabled, the device will respond to conditional search command if a timer alarm has occurred.
    • Constructor Summary

      Constructors 
      Constructor Description
      OneWireContainer21()
      Creates a new OneWireContainer for communication with a DS1921 Thermocron iButton.
      OneWireContainer21​(DSPortAdapter sourceAdapter, byte[] newAddress)
      Creates a new OneWireContainer for communication with a DS1921 Thermocron iButton.
      OneWireContainer21​(DSPortAdapter sourceAdapter, long newAddress)
      Creates a new OneWireContainer for communication with a DS1921 Thermocron iButton.
      OneWireContainer21​(DSPortAdapter sourceAdapter, java.lang.String newAddress)
      Creates a new OneWireContainer for communication with a DS1921 Thermocron iButton.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean canDisableClock()
      Checks to see if the clock can be disabled.
      void clearMemory()
      Clears the memory of any previous mission.
      double decodeTemperature​(byte tempByte)
      Converts a temperature from the DS1921 byte encoded format to degrees Celsius.
      void disableMission()
      Ends this DS1921's running mission.
      void doTemperatureConvert​(byte[] state)
      Performs a temperature conversion.
      void enableMission​(int sampleRate)
      Begins this DS1921's mission.
      byte encodeTemperature​(double temperature)
      Converts a temperature in degrees Celsius to a byte formatted for the DS1921.
      byte[] getAlarmHistory​(byte alarmBit)
      Returns an array containing the alarm log.
      boolean getAlarmStatus​(byte alarmBit, byte[] state)
      Returns true if the specified alarm has been triggered.
      java.util.Calendar getAlarmTime​(byte[] state)
      Gets the clock alarm time settings.
      java.lang.String getAlternateNames()
      Retrieves the alternate Maxim Integrated Products part numbers or names.
      long getClock​(byte[] state)
      Extracts the Real-Time clock value in milliseconds.
      long getClockAlarm​(byte[] state)
      Extracts the clock alarm value for the Real-Time clock.
      long getClockResolution()
      Gets the clock resolution in milliseconds
      java.lang.String getDescription()
      Gets a short description of the function of this iButton or 1-Wire Device type.
      int getDeviceSamplesCounter​(byte[] state)
      Determines the total number of samples taken by this Thermocron.
      long getFirstLogOffset​(byte[] state)
      Helps determine the times for values in a temperature log.
      boolean getFlag​(int register, byte bitMask)
      Gets the status of the specified flag from the specified register.
      boolean getFlag​(int register, byte bitMask, byte[] state)
      Gets the status of the specified flag from the specified register.
      double getHistogramBinWidth()
      This method returns the width of a histogram bin in degrees Celsius.
      double getHistogramLowTemperature()
      Retrieves the lowest temperature of the first histogram bin in degrees Celsius.
      int getMaxSpeed()
      Returns the maximum speed this iButton device can communicate at.
      double getMaxTemperature()
      Gets the maximum temperature in Celsius.
      java.util.Enumeration<MemoryBank> getMemoryBanks()
      Gets an enumeration of memory bank instances that implement one or more of the following interfaces: MemoryBank, PagedMemoryBank, and OTPMemoryBank.
      double getMinTemperature()
      Gets the minimum temperature in Celsius.
      int getMissionSamplesCounter​(byte[] state)
      Determines the number of samples taken on this mission.
      java.util.Calendar getMissionTimeStamp​(byte[] state)
      Returns the date and time that the last mission was started.
      java.lang.String getName()
      Gets the Maxim Integrated Products part number of the iButton or 1-Wire Device as a java.lang.String.
      double getOperatingRangeHighTemperature()
      This method returns the high temperature of the thermochron's operating temperature range.
      double getOperatingRangeLowTemperature()
      This method returns the low temperature of the thermochron's operating temperature range.
      double getPhysicalRangeHighTemperature()
      This method returns the high temperature of the thermochron's physical temperature range.
      double getPhysicalRangeLowTemperature()
      This method returns the low temperature of the thermochron's physical temperature range.
      int getSampleRate​(byte[] state)
      Returns the rate at which the DS1921 takes temperature samples.
      double getTemperature​(byte[] state)
      Gets the temperature value in Celsius from the state data retrieved from the readDevice() method.
      double getTemperatureAlarm​(int alarmType, byte[] state)
      Gets the specified temperature alarm value in Celsius from the state data retrieved from the readDevice() method.
      double getTemperatureAlarmResolution()
      Gets the temperature alarm resolution in Celsius.
      int[] getTemperatureHistogram()
      Returns an array of at most 64 counter bins holding the DS1921 histogram data (63 bins for the DS1921L-F5X and 64 bins for the DS1921H or DS1921Z).
      byte[] getTemperatureLog​(byte[] state)
      Returns the log of temperature measurements.
      double getTemperatureResolution()
      Retrieves the resolution with which the thermochron takes temperatures in degrees Celsius.
      double getTemperatureResolution​(byte[] state)
      Gets the current temperature resolution in Celsius from the state data retrieved from the readDevice() method.
      double[] getTemperatureResolutions()
      Get an array of available temperature resolutions in Celsius.
      boolean hasClockAlarm()
      Checks to see if the clock has an alarm feature.
      boolean hasSelectableTemperatureResolution()
      Checks to see if this device has selectable temperature resolution.
      boolean hasTemperatureAlarms()
      Checks to see if this temperature measuring device has high/low trip alarms.
      boolean isClockAlarmEnabled​(byte[] state)
      Checks if the clock alarm is enabled.
      boolean isClockAlarming​(byte[] state)
      Checks if the clock alarm flag has been set.
      boolean isClockRunning​(byte[] state)
      Checks if the device's oscillator is enabled.
      byte readByte​(int memAddr)
      Reads a single byte from the DS1921.
      byte[] readDevice()
      Retrieves the 1-Wire device sensor state.
      void setClock​(long time, byte[] state)
      Sets the Real-Time clock.
      void setClockAlarm​(int hours, int minutes, int seconds, int day, int alarmFrequency, byte[] state)
      Set the DS1921's alarm clock.
      void setClockAlarm​(long time, byte[] state)
      Sets the clock alarm.
      void setClockAlarmEnable​(boolean alarmEnable, byte[] state)
      Enables or disables the clock alarm.
      void setClockRunEnable​(boolean runEnable, byte[] state)
      Enables or disables the oscillator, turning the clock 'on' and 'off'.
      void setFlag​(int register, byte bitMask, boolean flagValue)
      Sets the status of the specified flag in the specified register.
      void setFlag​(int register, byte bitMask, boolean flagValue, byte[] state)
      Sets the status of the specified flag in the specified register.
      void setMissionStartDelay​(int missionStartDelay, byte[] state)
      Sets the time to wait before starting the mission.
      void setSpeedCheck​(boolean doSpeedCheck)
      Directs the container to avoid the calls to doSpeed() in methods that communicate with the Thermocron.
      void setTemperatureAlarm​(int alarmType, double alarmValue, byte[] state)
      Sets the temperature alarm value in Celsius in the provided state data.
      void setTemperatureResolution​(double resolution, byte[] state)
      Sets the current temperature resolution in Celsius in the provided state data.
      void setupContainer​(DSPortAdapter sourceAdapter, byte[] newAddress)
      Provides this container with the adapter object used to access this device and the address of the iButton or 1-Wire device.
      void setupContainer​(DSPortAdapter sourceAdapter, long newAddress)
      Provides this container with the adapter object used to access this device and the address of the iButton or 1-Wire device.
      void setupContainer​(DSPortAdapter sourceAdapter, java.lang.String newAddress)
      Provides this container with the adapter object used to access this device and the address of the iButton or 1-Wire device.
      void writeByte​(int memAddr, byte source)
      Writes a byte of data into the DS1921's memory.
      void writeDevice​(byte[] state)
      Writes the 1-Wire device sensor state that have been changed by 'set' methods.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Method Detail

      • setupContainer

        public void setupContainer​(DSPortAdapter sourceAdapter,
                                   byte[] newAddress)
        Provides this container with the adapter object used to access this device and the address of the iButton or 1-Wire device.
        Overrides:
        setupContainer in class OneWireContainer
        Parameters:
        sourceAdapter - adapter object required to communicate with this iButton
        newAddress - address of this 1-Wire device
        See Also:
        Address
      • setupContainer

        public void setupContainer​(DSPortAdapter sourceAdapter,
                                   long newAddress)
        Provides this container with the adapter object used to access this device and the address of the iButton or 1-Wire device.
        Overrides:
        setupContainer in class OneWireContainer
        Parameters:
        sourceAdapter - adapter object required to communicate with this iButton
        newAddress - address of this 1-Wire device
        See Also:
        Address
      • setupContainer

        public void setupContainer​(DSPortAdapter sourceAdapter,
                                   java.lang.String newAddress)
        Provides this container with the adapter object used to access this device and the address of the iButton or 1-Wire device.
        Overrides:
        setupContainer in class OneWireContainer
        Parameters:
        sourceAdapter - adapter object required to communicate with this iButton
        newAddress - address of this 1-Wire device
        See Also:
        Address
      • getName

        public java.lang.String getName()
        Gets the Maxim Integrated Products part number of the iButton or 1-Wire Device as a java.lang.String. For example "DS1992".
        Overrides:
        getName in class OneWireContainer
        Returns:
        iButton or 1-Wire device name
      • getAlternateNames

        public java.lang.String getAlternateNames()
        Retrieves the alternate Maxim Integrated Products part numbers or names. A 'family' of MicroLAN devices may have more than one part number depending on packaging. There can also be nicknames such as "Crypto iButton".
        Overrides:
        getAlternateNames in class OneWireContainer
        Returns:
        the alternate names for this iButton or 1-Wire device
      • getDescription

        public java.lang.String getDescription()
        Gets a short description of the function of this iButton or 1-Wire Device type.
        Overrides:
        getDescription in class OneWireContainer
        Returns:
        device description
      • setSpeedCheck

        public void setSpeedCheck​(boolean doSpeedCheck)
        Directs the container to avoid the calls to doSpeed() in methods that communicate with the Thermocron. To ensure that all parts can talk to the 1-Wire bus at their desired speed, each method contains a call to doSpeed(). However, this is an expensive operation. If a user manages the bus speed in an application, call this method with doSpeedCheck as false. The default behavior is to call doSpeed().
        Parameters:
        doSpeedCheck - true for doSpeed() to be called before every 1-Wire bus access, false to skip this expensive call
        See Also:
        OneWireContainer.doSpeed()
      • getPhysicalRangeLowTemperature

        public double getPhysicalRangeLowTemperature()
        This method returns the low temperature of the thermochron's physical temperature range. The physical range is the range of temperatures that the thermochron can record. The following is a list of physical ranges in degrees Celsius: DS1921L-F5X = physical range -40 to +85 DS1921H = physical range 15 to 46 DS1921Z = physical range -5 to 26
        Returns:
        the physical range low temperature in degrees Celsius
      • getPhysicalRangeHighTemperature

        public double getPhysicalRangeHighTemperature()
        This method returns the high temperature of the thermochron's physical temperature range. The physical range is the range of temperatures that the thermochron can record. The following is a list of physical ranges in degrees Celsius: DS1921L-F5X = physical range -40 to +85 DS1921H = physical range 15 to 46 DS1921Z = physical range -5 to 26
        Returns:
        the physical range low temperature in degrees Celsius
      • getOperatingRangeLowTemperature

        public double getOperatingRangeLowTemperature()
        This method returns the low temperature of the thermochron's operating temperature range. The operating range is the range of temperatures for which the thermochron can function properly. The following is a list of operating ranges in degrees Celsius: DS1921L-F50 = operating range -40 to +85. DS1921L-F51 = operating range -10 to +85. DS1921L-F52 = operating range -20 to +85. DS1921L-F53 = operating range -30 to +85. DS1921H = operating range -40 to +85 DS1921Z = operating range -40 to +85
        Returns:
        the operating range low temperature in degrees Celsius
      • getOperatingRangeHighTemperature

        public double getOperatingRangeHighTemperature()
        This method returns the high temperature of the thermochron's operating temperature range. The operating range is the range of temperatures for which the thermochron can function properly. The following is a list of operating ranges in degrees Celsius: DS1921L-F50 = operating range -40 to +85. DS1921L-F51 = operating range -10 to +85. DS1921L-F52 = operating range -20 to +85. DS1921L-F53 = operating range -30 to +85. DS1921H = operating range -40 to +85 DS1921Z = operating range -40 to +85
        Returns:
        the operating range high temperature in degrees Celsius
      • getTemperatureResolution

        public double getTemperatureResolution()
        Retrieves the resolution with which the thermochron takes temperatures in degrees Celsius.
        Returns:
        the temperature resolution of this thermochron.
      • getHistogramLowTemperature

        public double getHistogramLowTemperature()
        Retrieves the lowest temperature of the first histogram bin in degrees Celsius.
        Returns:
        the lowest histogram bin temperature.
      • getHistogramBinWidth

        public double getHistogramBinWidth()
        This method returns the width of a histogram bin in degrees Celsius.
        Returns:
        the width of a histogram bin for this thermochron.
      • decodeTemperature

        public double decodeTemperature​(byte tempByte)
        Converts a temperature from the DS1921 byte encoded format to degrees Celsius. The raw temperature readings are unsigned byte values, representing a 2.0 degree accuracy.
        Parameters:
        tempByte - raw DS1921 temperature reading
        Returns:
        temperature in degrees Celsius
        See Also:
        encodeTemperature(double)
      • encodeTemperature

        public byte encodeTemperature​(double temperature)
        Converts a temperature in degrees Celsius to a byte formatted for the DS1921.
        Parameters:
        temperature - the temperature (Celsius) to convert
        Returns:
        the temperature in raw DS1921 format
        See Also:
        decodeTemperature(byte)
      • writeByte

        public void writeByte​(int memAddr,
                              byte source)
                       throws OneWireIOException,
                              OneWireException
        Writes a byte of data into the DS1921's memory. Note that writing to the register page while a mission is in progress ends that mission. Also note that the preferred way to write a page is through the MemoryBank objects returned from the getMemoryBanks() method.
        Parameters:
        memAddr - the address for writing (in the range of 0x200-0x21F)
        source - the data byte to write
        Throws:
        OneWireIOException - on a 1-Wire communication error such as reading an incorrect CRC from a 1-Wire device. This could be caused by a physical interruption in the 1-Wire Network due to shorts or a newly arriving 1-Wire device issuing a 'presence pulse'.
        OneWireException - on a communication or setup error with the 1-Wire adapter
        See Also:
        readByte(int), getMemoryBanks()
      • readByte

        public byte readByte​(int memAddr)
                      throws OneWireIOException,
                             OneWireException
        Reads a single byte from the DS1921. Note that the preferred manner of reading from the DS1921 Thermocron is through the readDevice() method or through the MemoryBank objects returned in the getMemoryBanks() method.
        Parameters:
        memAddr - the address to read from (in the range of 0x200-0x21F)
        Returns:
        the data byte read
        Throws:
        OneWireIOException - on a 1-Wire communication error such as reading an incorrect CRC from a 1-Wire device. This could be caused by a physical interruption in the 1-Wire Network due to shorts or a newly arriving 1-Wire device issuing a 'presence pulse'.
        OneWireException - on a communication or setup error with the 1-Wire adapter
        See Also:
        writeByte(int,byte), readDevice(), getMemoryBanks()
      • getFlag

        public boolean getFlag​(int register,
                               byte bitMask,
                               byte[] state)

        Gets the status of the specified flag from the specified register. This method is the preferred manner of reading the control and status flags.

        For more information on valid values for the bitMask parameter, see the getFlag(int,byte) method.

        Parameters:
        register - address of register containing the flag (valid values are CONTROL_REGISTER and STATUS_REGISTER)
        bitMask - the flag to read (see getFlag(int,byte) for available options)
        state - current state of the device returned from readDevice()
        Returns:
        the status of the flag, where true signifies a "1" and false signifies a "0"
        See Also:
        getFlag(int,byte), readDevice(), setFlag(int,byte,boolean,byte[])
      • setFlag

        public void setFlag​(int register,
                            byte bitMask,
                            boolean flagValue)
                     throws OneWireIOException,
                            OneWireException

        Sets the status of the specified flag in the specified register. If a mission is in progress a OneWireIOException will be thrown (one cannot write to the registers while a mission is commencing). This method actually communicates with the DS1921 Thermocron. To improve performance if you intend to make multiple calls to this method, first call readDevice() and use the setFlag(int,byte,boolean,byte[]) method instead.

        For more information on valid values for the bitMask parameter, see the getFlag(int,byte) method.

        Parameters:
        register - address of register containing the flag (valid values are CONTROL_REGISTER and STATUS_REGISTER)
        bitMask - the flag to read (see getFlag(int,byte) for available options)
        flagValue - new value for the flag (true is logic "1")
        Throws:
        OneWireIOException - on a 1-Wire communication error such as reading an incorrect CRC from a 1-Wire device. This could be caused by a physical interruption in the 1-Wire Network due to shorts or a newly arriving 1-Wire device issuing a 'presence pulse'. In the case of the DS1921 Thermocron, this could also be due to a currently running mission.
        OneWireException - on a communication or setup error with the 1-Wire adapter
        See Also:
        getFlag(int,byte), getFlag(int,byte,byte[]), setFlag(int,byte,boolean,byte[]), readDevice()
      • setFlag

        public void setFlag​(int register,
                            byte bitMask,
                            boolean flagValue,
                            byte[] state)

        Sets the status of the specified flag in the specified register. If a mission is in progress a OneWireIOException will be thrown (one cannot write to the registers while a mission is commencing). This method is the preferred manner of setting the DS1921 status and control flags. The method writeDevice() must be called to finalize changes to the device. Note that multiple 'set' methods can be called before one call to writeDevice().

        For more information on valid values for the bitMask parameter, see the getFlag(int,byte) method.

        Parameters:
        register - address of register containing the flag (valid values are CONTROL_REGISTER and STATUS_REGISTER)
        bitMask - the flag to read (see getFlag(int,byte) for available options)
        flagValue - new value for the flag (true is logic "1")
        state - current state of the device returned from readDevice()
        See Also:
        getFlag(int,byte), getFlag(int,byte,byte[]), setFlag(int,byte,boolean), readDevice(), writeDevice(byte[])
      • enableMission

        public void enableMission​(int sampleRate)
                           throws OneWireIOException,
                                  OneWireException

        Begins this DS1921's mission. If a mission is already in progress, this will throw a OneWireIOException. The mission will wait the number of minutes specified by the mission start delay (use setMissionStartDelay()) before beginning.

        Note that this method actually communicates with the DS1921 Thermocron. No call to writeDevice() is required to finalize mission enabling. However, some flags (such as the mission start delay) may need to be set with a call to writeDevice() before the mission is enabled. See the usage section above for an example of starting a mission.

        Parameters:
        sampleRate - the number of minutes to wait in between temperature samples (valid values are 1 to 255)
        Throws:
        OneWireIOException - on a 1-Wire communication error such as reading an incorrect CRC from a 1-Wire device. This could be caused by a physical interruption in the 1-Wire Network due to shorts or a newly arriving 1-Wire device issuing a 'presence pulse'. In the case of the DS1921 Thermocron, this could also be due to a currently running mission.
        OneWireException - on a communication or setup error with the 1-Wire adapter
        See Also:
        disableMission(), setMissionStartDelay(int,byte[]), writeDevice(byte[])
      • disableMission

        public void disableMission()
                            throws OneWireIOException,
                                   OneWireException
        Ends this DS1921's running mission. Note that this method actually communicates with the DS1921 Thermocron. No additional call to writeDevice(byte[]) is required.
        Throws:
        OneWireIOException - on a 1-Wire communication error such as reading an incorrect CRC from a 1-Wire device. This could be caused by a physical interruption in the 1-Wire Network due to shorts or a newly arriving 1-Wire device issuing a 'presence pulse'.
        OneWireException - on a communication or setup error with the 1-Wire adapter
        See Also:
        enableMission(int)
      • setMissionStartDelay

        public void setMissionStartDelay​(int missionStartDelay,
                                         byte[] state)

        Sets the time to wait before starting the mission. The DS1921 will sleep missionStartDelay minutes after the mission is enabled with enableMission(int), then begin taking samples. Only the least significant 16 bits of missionStartDelay are relevant.

        The method writeDevice() must be called to finalize changes to the device. Note that multiple 'set' methods can be called before one call to writeDevice().

        Parameters:
        missionStartDelay - the time in minutes to delay the first sample
        state - current state of the device returned from readDevice()
        See Also:
        readDevice(), writeDevice(byte[]), enableMission(int)
      • clearMemory

        public void clearMemory()
                         throws OneWireIOException,
                                OneWireException

        Clears the memory of any previous mission. The memory must be cleared before setting up a new mission. If a mission is in progress a OneWireIOException is thrown.

        The Clear Memory command clears the Thermocron's memory at address 220h and higher. It also clears the sample rate, mission start delay, mission time stamp, and mission samples counter.

        Note that this method actually communicates with the DS1921 Thermocron. No call to writeDevice(byte[]) is necessary to finalize this activity.

        Throws:
        OneWireIOException - on a 1-Wire communication error such as reading an incorrect CRC from a 1-Wire device. This could be caused by a physical interruption in the 1-Wire Network due to shorts or a newly arriving 1-Wire device issuing a 'presence pulse'. In the case of the DS1921 Thermocron, this could also be due to a currently running mission.
        OneWireException - on a communication or setup error with the 1-Wire adapter
        See Also:
        enableMission(int), writeDevice(byte[])
      • getAlarmTime

        public java.util.Calendar getAlarmTime​(byte[] state)

        Gets the clock alarm time settings. The alarm settings used by the Thermocron are Hour, Minute, Second, and Day of Week. Note that not all values in the returned java.util.Calendar object are valid. Only four values in the Calendar should be used. The field names for these values are:

         
              Calendar.DAY_OF_MONTH
              Calendar.HOUR_OF_DAY
              Calendar.MINUTE
              Calendar.SECOND
         

        The hour is reported in 24-hour format. Use the method getClockAlarm(byte[]) to find out the next time an alarm event will occur.

        Parameters:
        state - current state of the device returned from readDevice()
        Returns:
        the alarm clock time and day of the week
        See Also:
        setClockAlarm(int,int,int,int,int,byte[]), readDevice(), getClockAlarm(byte[])
      • setClockAlarm

        public void setClockAlarm​(int hours,
                                  int minutes,
                                  int seconds,
                                  int day,
                                  int alarmFrequency,
                                  byte[] state)
        Set the DS1921's alarm clock. Some of the parameters might be unimportant depending on the alarm frequency setting. For instance, if the alarm frequency setting is ONCE_PER_MINUTE, then the hour argument is irrelevant.

        Valid values for alarmFrequency are:

         
            ONCE_PER_SECOND
            ONCE_PER_MINUTE
            ONCE_PER_HOUR
            ONCE_PER_DAY
            ONCE_PER_WEEK
         

        The method writeDevice() must be called to finalize changes to the device. Note that multiple 'set' methods can be called before one call to writeDevice().

        Parameters:
        hours - the hour of the day (0-23)
        minutes - the minute setting (0-59)
        seconds - the second setting (0-59)
        day - the day of the week (1-7, 1==Sunday)
        alarmFrequency - frequency that the alarm should occur at
        state - current state of the device returned from readDevice()
        See Also:
        readDevice(), writeDevice(byte[]), getClockAlarm(byte[]), ONCE_PER_SECOND, ONCE_PER_MINUTE, ONCE_PER_HOUR, ONCE_PER_DAY, ONCE_PER_WEEK
      • getSampleRate

        public int getSampleRate​(byte[] state)
        Returns the rate at which the DS1921 takes temperature samples. This rate is set when the mission is enabled (in the method enableMission(int).
        Parameters:
        state - current state of the device returned from readDevice()
        Returns:
        the time, in minutes, between temperature readings
        See Also:
        enableMission(int), readDevice()
      • getMissionSamplesCounter

        public int getMissionSamplesCounter​(byte[] state)
        Determines the number of samples taken on this mission. Only the last 2048 samples appear in the Thermocron's log, though all readings from the current mission are logged in the histogram.
        Parameters:
        state - current state of the device returned from readDevice()
        Returns:
        the number of samples taken in the current mission
        See Also:
        readDevice(), getDeviceSamplesCounter(byte[])
      • getDeviceSamplesCounter

        public int getDeviceSamplesCounter​(byte[] state)

        Determines the total number of samples taken by this Thermocron. This includes samples taken in past missions. It also includes 'forced' readings. A 'forced' reading refers to a reading taken when the Thermocron does not have a running mission and is instructed to read the current temperature.

        The DS1921 Thermocron is tested to last for 1 million temperature readings.

        Parameters:
        state - current state of the device returned from readDevice()
        Returns:
        the total number of measurements taken by this Thermocron
        See Also:
        readDevice(), getMissionSamplesCounter(byte[])
      • getMissionTimeStamp

        public java.util.Calendar getMissionTimeStamp​(byte[] state)
        Returns the date and time that the last mission was started. The values in the java.util.Calendar object are fully specified. In other words, the year, month, date, hour, minute, and second are all valid in the returned object.
        Parameters:
        state - current state of the device returned from readDevice()
        Returns:
        the date and time that the last mission was started
        See Also:
        readDevice()
      • getFirstLogOffset

        public long getFirstLogOffset​(byte[] state)

        Helps determine the times for values in a temperature log. If rollover is enabled, temperature log entries will over-write previous entries once more than 2048 logs are written. The returned value can be added to the underlying millisecond value of getMissionTimeStamp() to determine the time that the 'first' log entry actually occurred.

         
              //ds1921 is a OneWireContainer21
              byte[] state = ds1921.readDevice();
              Calendar c = ds1921.getMissionTimeStamp(state);
              //find the time for the first log entry
              long first_entry = c.getTime().getTime();
              first_entry += ds1921.getFirstLogOffset(state);
              . . .
         
         

        Be cautious of Java's Daylight Savings Time offsets when using this function--if you use the Date or Calendar class to print this out, Java may try to automatically format the java.lang.String to handle Daylight Savings Time, resulting in offset by 1 hour problems.

        Parameters:
        state - current state of the device returned from readDevice()
        Returns:
        milliseconds between the beginning of the mission and the time of the first log entry reported from getTemperatureLog()
        See Also:
        readDevice(), getMissionTimeStamp(byte[]), getTemperatureLog(byte[])
      • getTemperatureLog

        public byte[] getTemperatureLog​(byte[] state)
                                 throws OneWireIOException,
                                        OneWireException

        Returns the log of temperature measurements. Each byte in the returned array is an independent sample. Use the method decodeTemperature(byte) to get the double value of the encoded temperature. See the DS1921 datasheet for more on the data's encoding scheme. The array's length equals the number of measurements taken thus far. The temperature log can be read while a mission is still in progress.

        Note that although this method takes the device state as a parameter, this method still must communicate directly with the Thermocron to read the log.

        Parameters:
        state - current state of the device returned from readDevice()
        Returns:
        the DS1921's encoded temperature log
        Throws:
        OneWireIOException - on a 1-Wire communication error such as reading an incorrect CRC from a 1-Wire device. This could be caused by a physical interruption in the 1-Wire Network due to shorts or a newly arriving 1-Wire device issuing a 'presence pulse'.
        OneWireException - on a communication or setup error with the 1-Wire adapter
        See Also:
        decodeTemperature(byte), readDevice(), getFirstLogOffset(byte[]), getMissionTimeStamp(byte[])
      • getTemperatureHistogram

        public int[] getTemperatureHistogram()
                                      throws OneWireIOException,
                                             OneWireException

        Returns an array of at most 64 counter bins holding the DS1921 histogram data (63 bins for the DS1921L-F5X and 64 bins for the DS1921H or DS1921Z). For the temperature histogram, the DS1921 provides bins that each consist of a 16-bit, non rolling-over binary counter that is incremented each time a temperature value acquired during a mission falls into the range of the bin. The bin to be updated is determined by cutting off the two least significant bits of the binary temperature value. For example, on a DS1921L-F5X, bin 0 will hold the counter for temperatures ranging from -40 to -38.5 (Celsius) and lower. Bin 1 is associated with the range of -38 to 36.5 and so on. The last bin, in this case bin 62, holds temperature values of 84 degrees and higher. Please see the respective DS1921H or DS1921Z datasheets for their bin arrangements. The temperature histogram can be read while a mission is still in progress.

        Returns:
        the 63 temperature counters
        Throws:
        OneWireIOException - on a 1-Wire communication error such as reading an incorrect CRC from a 1-Wire device. This could be caused by a physical interruption in the 1-Wire Network due to shorts or a newly arriving 1-Wire device issuing a 'presence pulse'.
        OneWireException - on a communication or setup error with the 1-Wire adapter
      • getAlarmStatus

        public boolean getAlarmStatus​(byte alarmBit,
                                      byte[] state)
        Returns true if the specified alarm has been triggered. Valid values for the alarmBit parameter are:
             TEMPERATURE_LOW_ALARM
             TEMPERATURE_HIGH_ALARM
             TIMER_ALARM
         
        Parameters:
        alarmBit - the alarm to check
        state - current state of the device returned from readDevice()
        Returns:
        if the specified alarm has been triggered
        See Also:
        TEMPERATURE_LOW_ALARM, TEMPERATURE_HIGH_ALARM, TIMER_ALARM, readDevice(), getAlarmHistory(byte)
      • getAlarmHistory

        public byte[] getAlarmHistory​(byte alarmBit)
                               throws OneWireIOException,
                                      OneWireException

        Returns an array containing the alarm log. The DS1921 contains two separate alarm logs. One for the high temperature alarm and one for the low temperature alarm. Each log can store up to 12 log entries and each log entry will record up to 255 consecutive alarm violations.

        The returned array is not altered from its representation on the DS1921 Thermocron. It is therefore up to the caller to interpret the data. The number of logs in this alarm history is equal to the array length divided by 4, since each entry is 4 bytes. The first three bytes are the number of samples into the mission that the alarm occurred. The fourth byte is the number of consecutive samples that violated the alarm. To extract the starting offset and number of violations from the array:

               byte[] data = ds1921.getAlarmHistory(OneWireContainer21.TEMPERATURE_HIGH_ALARM);
               int start_offset;
               int violation_count;
               . . .
               for (int i=0;i < data.length/4; i++)
               {
                   start_offset = (data [i * 4] & 0x0ff)
                             | ((data [i * 4 + 1] << 8) & 0x0ff00)
                             | ((data [i * 4 + 2] << 16) & 0x0ff0000);
                   violation_count = 0x0ff & data[i*4+3];
        
                   . . .
        
                   // note: you may find it useful to multiply start_offset
                   //       by getSampleRate() in order to get the number of
                   //       minutes into the mission that the violation occurred
                   //       on.  You can do the same with violation_count
                   //       to determine how long the violation lasted.
               }
         

        Acceptable values for the alarmBit parameter are:

         
             TEMPERATURE_LOW_ALARM
             TEMPERATURE_HIGH_ALARM
         

        Parameters:
        alarmBit - the alarm log to get
        Returns:
        the time/duration of the alarm (see above for the structure of the array)
        Throws:
        OneWireIOException - on a 1-Wire communication error such as reading an incorrect CRC from a 1-Wire device. This could be caused by a physical interruption in the 1-Wire Network due to shorts or a newly arriving 1-Wire device issuing a 'presence pulse'.
        OneWireException - on a communication or setup error with the 1-Wire adapter
        See Also:
        getAlarmStatus(byte,byte[])
      • readDevice

        public byte[] readDevice()
                          throws OneWireIOException,
                                 OneWireException
        Retrieves the 1-Wire device sensor state. This state is returned as a byte array. Pass this byte array to the 'get' and 'set' methods. If the device state needs to be changed then call the 'writeDevice' to finalize the changes.
        Specified by:
        readDevice in interface OneWireSensor
        Returns:
        1-Wire device sensor state
        Throws:
        OneWireIOException - on a 1-Wire communication error such as reading an incorrect CRC from a 1-Wire device. This could be caused by a physical interruption in the 1-Wire Network due to shorts or a newly arriving 1-Wire device issuing a 'presence pulse'.
        OneWireException - on a communication or setup error with the 1-Wire adapter
      • writeDevice

        public void writeDevice​(byte[] state)
                         throws OneWireIOException,
                                OneWireException
        Writes the 1-Wire device sensor state that have been changed by 'set' methods. Only the state registers that changed are updated. This is done by referencing a field information appended to the state data.
        Specified by:
        writeDevice in interface OneWireSensor
        Parameters:
        state - 1-Wire device sensor state
        Throws:
        OneWireIOException - on a 1-Wire communication error such as reading an incorrect CRC from a 1-Wire device. This could be caused by a physical interruption in the 1-Wire Network due to shorts or a newly arriving 1-Wire device issuing a 'presence pulse'.
        OneWireException - on a communication or setup error with the 1-Wire adapter
      • doTemperatureConvert

        public void doTemperatureConvert​(byte[] state)
                                  throws OneWireIOException,
                                         OneWireException
        Performs a temperature conversion. Use the state information to calculate the conversion time.
        Specified by:
        doTemperatureConvert in interface TemperatureContainer
        Parameters:
        state - byte array with device state information
        Throws:
        OneWireIOException - on a 1-Wire communication error such as reading an incorrect CRC from a 1-Wire device. This could be caused by a physical interruption in the 1-Wire Network due to shorts or a newly arriving 1-Wire device issuing a 'presence pulse'. In the case of the DS1921 Thermocron, this could also be due to a currently running mission.
        OneWireException - on a communication or setup error with the 1-Wire adapter
      • getTemperature

        public double getTemperature​(byte[] state)
        Gets the temperature value in Celsius from the state data retrieved from the readDevice() method.
        Specified by:
        getTemperature in interface TemperatureContainer
        Parameters:
        state - byte array with device state information
        Returns:
        temperature in Celsius from the last doTemperatureConvert()
      • getTemperatureAlarm

        public double getTemperatureAlarm​(int alarmType,
                                          byte[] state)
        Gets the specified temperature alarm value in Celsius from the state data retrieved from the readDevice() method.
        Specified by:
        getTemperatureAlarm in interface TemperatureContainer
        Parameters:
        alarmType - valid value: ALARM_HIGH or ALARM_LOW
        state - byte array with device state information
        Returns:
        temperature alarm trip values in Celsius for this 1-wire device
        See Also:
        hasTemperatureAlarms(), setTemperatureAlarm(int, double, byte[])
      • setTemperatureAlarm

        public void setTemperatureAlarm​(int alarmType,
                                        double alarmValue,
                                        byte[] state)
        Sets the temperature alarm value in Celsius in the provided state data. Use the method writeDevice() with this data to finalize the change to the device.
        Specified by:
        setTemperatureAlarm in interface TemperatureContainer
        Parameters:
        alarmType - valid value: ALARM_HIGH or ALARM_LOW
        alarmValue - alarm trip value in Celsius
        state - byte array with device state information
        See Also:
        hasTemperatureAlarms(), getTemperatureAlarm(int, byte[])
      • getClockResolution

        public long getClockResolution()
        Gets the clock resolution in milliseconds
        Specified by:
        getClockResolution in interface ClockContainer
        Returns:
        the clock resolution in milliseconds
      • getClock

        public long getClock​(byte[] state)
        Extracts the Real-Time clock value in milliseconds.
        Specified by:
        getClock in interface ClockContainer
        Parameters:
        state - current state of the device returned from readDevice()
        Returns:
        the time represented in this clock in milliseconds since 1970
        See Also:
        OneWireSensor.readDevice(), setClock(long,byte[])
      • setClock

        public void setClock​(long time,
                             byte[] state)
        Sets the Real-Time clock. The method writeDevice() must be called to finalize changes to the device. Note that multiple 'set' methods can be called before one call to writeDevice().
        Specified by:
        setClock in interface ClockContainer
        Parameters:
        time - new value for the Real-Time clock, in milliseconds since January 1, 1970
        state - current state of the device returned from readDevice()
        See Also:
        OneWireSensor.writeDevice(byte[]), getClock(byte[])
      • setClockRunEnable

        public void setClockRunEnable​(boolean runEnable,
                                      byte[] state)
        Enables or disables the oscillator, turning the clock 'on' and 'off'. The method writeDevice() must be called to finalize changes to the device. Note that multiple 'set' methods can be called before one call to writeDevice(). Also note that not all clock devices can disable their oscillators. Check to see if this device can disable its oscillator first by calling the canDisableClock() method.
        Specified by:
        setClockRunEnable in interface ClockContainer
        Parameters:
        runEnable - true to enable the clock oscillator
        state - current state of the device returned from readDevice()
        See Also:
        OneWireSensor.writeDevice(byte[]), canDisableClock(), isClockRunning(byte[])