1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
|
/*
* Author: Jon Trulson <jtrulson@ics.com>
* Copyright (c) 2016 Intel Corporation.
*
* Permission is hereby granted, free of charge, to any person obtaining
* a copy of this software and associated documentation files (the
* "Software"), to deal in the Software without restriction, including
* without limitation the rights to use, copy, modify, merge, publish,
* distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so, subject to
* the following conditions:
*
* The above copyright notice and this permission notice shall be
* included in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
* LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
* WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
#pragma once
#include <string>
#include <iostream>
#include <map>
#include <stdlib.h>
#include <unistd.h>
#include <string.h>
#include <mraa/common.hpp>
#include <mraa/uart_ow.hpp>
#define DS18B20_DEFAULT_UART 0
namespace upm {
/**
* @brief DS18B20 1-Wire Temperature Sensor
* @defgroup ds18b20 libupm-ds18b20
* @ingroup maxim uart
*/
/**
* @library ds18b20
* @sensor ds18b20
* @comname DS18B20 1-Wire Temperature Sensor
* @type uart
* @man maxim
* @con uart
* @web https://www.sparkfun.com/products/11050
*
* @brief API for the DS18B20 1-Wire Temperature Sensor
*
* This driver supports, and was tested with, a DS18B20 with
* external power.
*
* Multiple DS18B20 devices can be connected to this bus. This
* module will identify all such devices connected, and allow you
* to access them using an index starting at 0.
*
* Parasitic power is not currently supported due
* to the very tight 10us limit on switching a GPIO properly to
* supply power during certain operations. For this reason, you
* should use external power for your sensors.
*
* Setting the alarm values (Tl, Th) is also not supported, since
* this is only useful when doing a 1-wire device search looking
* for devices in an alarm state, a capability not yet supported
* in MRAA. In reality, this is trivial to handle yourself in
* your application.
*
* This device requires the use of a UART to provide access to a
* Dallas 1-wire bus, via a new facility supported by MRAA (once
* the relevant PR is accepted), using the UartOW access class.
* It is important to realize that the UART is only being used to
* access and control a Dallas 1-wire compliant bus, it is not
* actually a UART device.
*
* @snippet ds18b20.cxx Interesting
*/
class DS18B20 {
public:
// The family code for these devices. We handle all of them that
// are found on the bus.
static const uint8_t DS18B20_FAMILY_CODE = 0x28;
// commands
typedef enum {
CMD_CONVERT = 0x44, // start a temp conversion
CMD_WRITE_SCRATCHPAD = 0x4e,
CMD_READ_SCRATCHPAD = 0xbe,
CMD_COPY_SCRATCHPAD = 0x48, // copy scratchpad to EEPROM
CMD_RECALL_EEPROM = 0xb8, // copy EEPROM to scratchpad
CMD_READ_POWER_SUPPLY = 0xb4 // parasitically powered?
} CMD_T;
// config register (scratchpad[4])
typedef enum {
CFG_RESOLUTION_R0 = 0x20,
CFG_RESOLUTION_R1 = 0x40,
_CFG_RESOLUTION_MASK = 3,
_CFG_RESOLUTION_SHIFT = 5
// all other bits reserved and non-writable
} CFG_BITS_T;
typedef enum {
RESOLUTION_9BITS = 0, // 93.75ms (tconv/8)
RESOLUTION_10BITS = 1, // 187.5 (tconv/4)
RESOLUTION_11BITS = 2, // 375ms (tconv/2)
RESOLUTION_12BITS = 3 // 750ms (tconv)
} RESOLUTIONS_T;
/**
* DS18B20 object constructor
*
* @param uart Default UART to use (0 or 1). Default is 0.
*/
DS18B20(int uart=DS18B20_DEFAULT_UART);
/**
* DS18B20 object destructor
*/
~DS18B20();
/**
* This method will search the 1-wire bus and store information on
* each device detected on the bus. If no devices are found, an
* exception is thrown. Once this function completes
* successfully, you can use devicesFound() to determine how many
* devices were detected. This method must be executed first
* before any others below.
*/
void init();
/**
* Update our stored temperature for a device. This method must
* be called prior to getTemperature().
*
* @param index The device index to access (starts at 0). Specify
* -1 to query all detected devices. Default: -1
*/
void update(int index=-1);
/**
* Get the current temperature. update() must have been called
* prior to calling this method.
*
* @param index The device index to access (starts at 0).
* @param fahrenheit true to return the temperature in degrees
* fahrenheit, false to return the temperature in degrees celcius.
* The default is false (degrees Celcius).
* @return The last temperature reading in Celcius or Fahrenheit
*/
float getTemperature(int index, bool fahrenheit=false);
/**
* Set the device resolution for a device. These devices support
* 9, 10, 11, and 12 bits of resolution, with the default from the
* factory at 12 bits.
*
* @param index The device index to access (starts at 0).
* @param res One of the RESOLUTIONS_T values
*/
void setResolution(int index, RESOLUTIONS_T res);
/**
* Copy the device's scratchpad memory to the EEPROM. This
* includes the configuration byte (resolution).
*
* @param index The device index to access (starts at 0).
*/
void copyScratchPad(int index);
/**
* Copy the device's EEPROM memory to the scratchpad. This method
* will return when the copy completes. This operation is
* performed by the device automatically on power up, so it is
* rarely needed.
*
* @param index The device index to access (starts at 0).
*/
void recallEEPROM(int index);
/**
* This method will return the number of DS18B20 devices that were
* found on the bus by init().
*
* @return number of DS18B20's that were found on the bus
*/
int devicesFound()
{
return m_devicesFound;
}
/**
* Return an 8 byte string representing the unique device ID
* (1-wire romcode) for a given device index.
*
* @param index The device index to access (starts at 0).
* @return 8 byte string representing the 1-wire device's unique
* romcode.
*/
std::string getId(int index)
{
if (index < 0 || index >= m_devicesFound)
{
throw std::out_of_range(std::string(__FUNCTION__) +
": device index out of range");
}
return m_deviceMap[index].id;
}
protected:
mraa::UartOW m_uart;
// the total number of devices found
int m_devicesFound;
// this struct will generate SWIG warnings on build, but as it's not
// exposed outside the class, they can be safely ignored
// data we need to store for each sensor we are dealing with
typedef struct {
std::string id; // 8-byte romcode id
float temperature;
RESOLUTIONS_T resolution;
} sensor_info_t;
std::map<int, sensor_info_t> m_deviceMap;
private:
// internal utility function to read temperature from a single
// device
float readSingleTemp(int index);
};
}
|
