Raspberries/mraa
Private
Public Access
2
0
Fork 0
Code Activity

uart_ow: Initial support for Dallas 1-wire over UART support for MRAA

Browse Source 
This commit introduces support for Dallas Semiconductor (DS) 1-wire
compliant device support using an available UART device.

The principle of operation is described in the following Application
note by Maxim Electronics:

https://www.maximintegrated.com/en/app-notes/index.mvp/id/214

with help (1-wire search) from:
https://www.maximintegrated.com/en/app-notes/index.mvp/id/187

It has been tested on Galileo 2 and Edison, with 2 DS 1-wire devices,
the DS18B20 and DS2413 connected to the bus.  A UPM driver for the
DS2413 is already complete and a PR will be submitted after this one.

It is important that you use a UART with CMOS/TTL level voltages
(3.3v/5v) RX and TX lines.  DO NOT use standard RS232 level voltages
or you are going to have a bad day.

In order for this to work, a simple interface circuit, using a single
diode must be constructed:

(forgive my "Asciihematic" :)

-|
U|
A| TX---|<--+
R|          |
T| RX-------o--------o 1-wire data bus
-|

The diode on TX is a 1N4148 (cheap and common), with the cathode
connected to TX, and the anode connected to RX and the 1-wire data
line.

The 1-wire data line requires a pull-up resistor, as the DS 1-wire
spec requires. 4.7-5K is typical for DS 1-wire buses.

NOTE: DHT-type (temp/humidity sensor) 1-wire devices ARE NOT DS 1-wire
compliant, and will not work with this code/circuit unfortunately.

Also note, this will use up one of your UARTs, which cannot be used
for any other purpose (ie: to access true UART-type serial devices).

You can however, connect as many DS 1-wire devices as feasible to this
UART, as it will function as a DS 1-wire bus master.

Signed-off-by: Jon Trulson <jtrulson@ics.com>
Signed-off-by: Brendan Le Foll <brendan.le.foll@intel.com>
This commit is contained in:
Jon Trulson
2015-12-15 17:11:14 -07:00
committed by Brendan Le Foll
parent 69d9c26e6e
commit a379eb7bf6
12 changed files with 1143 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
api/mraa.h
View File

@@ -33,6 +33,7 @@ extern "C" {
#include "mraa/spi.h"
#include "mraa/i2c.h"
#include "mraa/uart.h"
#include "mraa/uart_ow.h"
#ifdef __cplusplus
}

3
api/mraa/types.h
View File

@@ -207,6 +207,9 @@ typedef enum {
MRAA_ERROR_INVALID_PLATFORM = 10, /**< Platform not recognised */
MRAA_ERROR_PLATFORM_NOT_INITIALISED = 11, /**< Board information not initialised */
MRAA_ERROR_PLATFORM_ALREADY_INITIALISED = 0, /**< Board is already initialised, same as MRAA_SUCESS */
MRAA_ERROR_UART_OW_SHORTED = 12, /**< UART OW Short Circuit Detected*/
MRAA_ERROR_UART_OW_NO_DEVICES = 13, /**< UART OW No devices detected */
MRAA_ERROR_UART_OW_DATA_ERROR = 14, /**< UART OW Data/Bus error detected */
MRAA_ERROR_UNSPECIFIED = 99 /**< Unknown Error */
} mraa_result_t;

3
api/mraa/types.hpp
View File

@@ -205,6 +205,9 @@ typedef enum {
ERROR_INVALID_PLATFORM = 10, /**< Platform not recognised */
ERROR_PLATFORM_NOT_INITIALISED = 11, /**< Board information not initialised */
ERROR_PLATFORM_ALREADY_INITIALISED = 0, /**< Board is already initialised, same as SUCCESS */
ERROR_UART_OW_SHORTED = 12, /**< UART OW Short Circuit Detected*/
ERROR_UART_OW_NO_DEVICES = 13, /**< UART OW No devices detected */
ERROR_UART_OW_DATA_ERROR = 14, /**< UART OW Data/Bus error detected */
ERROR_UNSPECIFIED = 99 /**< Unknown Error */
} Result;

189
api/mraa/uart_ow.h Normal file
View File

@@ -0,0 +1,189 @@
/*
* 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
/**
* @file
* @brief UART OW module
*
* This module allows one to use MRAA's UART support in order to
* interact with Dallas 1-wire compliant devices on a 1-wire bus. It
* makes use of the UART for timing purposes. The principle of
* operation is described here:
* https://www.maximintegrated.com/en/app-notes/index.mvp/id/214
*
* It is important the you use a UART with CMOS/TTL level voltages
* (3.3v/5v) RX and TX lines. DO NOT use standard RS232 level
* voltages, or you are going to have a bad day.
*
* In addition, a diode should be placed across the RX and
* TX lines like so:
*
* -|
* U|
* A| TX---|<--+
* R| |
* T| RX-------o--------o 1-wire data bus
* -|
*
* The diode on TX is a 1N4148 (cheap and common), with the cathode
* connected to TX, and the anode connected to RX and the rest of the
* 1-wire data line.
*
* @snippet uart_ow.c Interesting
*/
#ifdef __cplusplus
extern "C" {
#endif
#include <stdio.h>
#include "common.h"
/* for now, we simply use the normal MRAA UART context */
typedef struct _uart* mraa_uart_ow_context;
/* 8 bytes (64 bits) for a device rom code */
static const int MRAA_UART_OW_ROMCODE_SIZE = 8;
/**
* UART One Wire ROM related Command bytes
*/
typedef enum {
MRAA_UART_OW_CMD_READ_ROM = 0x33, /**< read rom, when only one device on bus */
MRAA_UART_OW_CMD_MATCH_ROM = 0x55, /**< match a specific rom code */
MRAA_UART_OW_CMD_SKIP_ROM = 0xcc, /**< skip match/search rom */
MRAA_UART_OW_CMD_SEARCH_ROM_ALARM = 0xec, /**< search all roms in alarm state */
MRAA_UART_OW_CMD_SEARCH_ROM = 0xf0 /**< search all rom codes */
} mraa_uart_ow_rom_cmd_t;
/**
* Initialise uart_ow_context, uses UART board mapping
*
* @param uart the index of the uart set to use
* @return uart_ow context or NULL
*/
mraa_uart_ow_context mraa_uart_ow_init(int uart);
/**
* Initialise a raw uart_ow_context. No board setup.
*
* @param path for example "/dev/ttyS0"
* @return uart_ow context or NULL
*/
mraa_uart_ow_context mraa_uart_ow_init_raw(const char* path);
/**
* Get char pointer with tty device path within Linux
* For example. Could point to "/dev/ttyS0"
*
* @param dev uart_ow context
* @return char pointer of device path
*/
const char* mraa_uart_ow_get_dev_path(mraa_uart_ow_context dev);
/**
* Destroy a mraa_uart_ow_context
*
* @param dev uart_ow context
* @return mraa_result_t
*/
mraa_result_t mraa_uart_ow_stop(mraa_uart_ow_context dev);
/**
* Read a byte from the 1-wire bus
*
* @param dev uart_ow context
* @return the byte read
*/
uint8_t mraa_uart_ow_read_byte(mraa_uart_ow_context dev);
/**
* Write a byte to a 1-wire bus
*
* @param dev uart_ow context
* @param byte the byte to write to the bus
* @return the byte read back during the time slot
*/
uint8_t mraa_uart_ow_write_byte(mraa_uart_ow_context dev, uint8_t byte);
/**
* Write a bit to a 1-wire bus and read a bit corresponding to the
* time slot back. This is possible due to the way we wired the TX
* and RX together with a diode, forming a loopback.
*
* @param dev uart_ow context
* @param bit the bit to write to the bus
* @return the bit read back during the time slot
*/
uint8_t mraa_uart_ow_bit(mraa_uart_ow_context dev, uint8_t bit);
/**
* Send a reset pulse to the 1-wire bus and test for device presence
*
* @param dev uart_ow context
* @return one of the mraa_result_t values
*/
mraa_result_t mraa_uart_ow_reset(mraa_uart_ow_context dev);
/**
* Begin a rom code search of the 1-wire bus. This function
* implements the 1-wire search algorithm. See the uart_ow.c example
* for an idea on how to use this function to identify all devices
* present on the bus.
*
* @param dev uart_ow context
* @param start true to start a new search from scratch, false to
* continue an existing search
* @param id the 8-byte rom code id of the current matched device when
* a device is found
* @return one of the mraa_result_t values
*/
mraa_result_t mraa_uart_ow_rom_search(mraa_uart_ow_context dev, mraa_boolean_t start, uint8_t* id);
/**
* Send a command byte to a device on the 1-wire bus
*
* @param dev uart_ow context
* @param command the command byte to send
* @param id the rom code id of the device to receive the command,
* NULL for all devices on the bus
* @return one of the mraa_result_t values
*/
mraa_result_t mraa_uart_ow_command(mraa_uart_ow_context dev, uint8_t command, uint8_t* id);
/**
* Perform a Dallas 1-wire compliant CRC8 computation on a buffer
*
* @param buffer the buffer containing the data
* @param length the length of the buffer
* @return the computed CRC
*/
uint8_t mraa_uart_ow_crc8(uint8_t* buffer, uint16_t length);
#ifdef __cplusplus
}
#endif

260
api/mraa/uart_ow.hpp Normal file
View File

@@ -0,0 +1,260 @@
/*
* 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 "uart_ow.h"
#include "types.hpp"
#include <stdexcept>
#include <cstring>
namespace mraa
{
/**
* @brief API for UART One Wire
*
* This file defines the UartOW (UART to Dallas 1-wire) interface for libmraa
*
* @snippet UartOW.cpp Interesting
*/
class UartOW
{
public:
/**
* UartOW Constructor, takes a pin number which will map directly to the
* linux uart number, this 'enables' the uart, nothing more
*
* @param uart the index of the uart to use
*/
UartOW(int uart)
{
m_uart = mraa_uart_ow_init(uart);
if (m_uart == NULL) {
throw std::invalid_argument("Error initialising UART_OW");
}
}
/**
* UartOW Constructor, takes a string to the path of the serial
* interface that is needed.
*
* @param path the file path for the UART to use
*/
UartOW(std::string path)
{
m_uart = mraa_uart_ow_init_raw(path.c_str());
if (m_uart == NULL) {
throw std::invalid_argument("Error initialising UART");
}
}
/**
* Uart destructor
*/
~UartOW()
{
mraa_uart_ow_stop(m_uart);
}
/**
* Get string with tty device path within Linux
* For example. Could point to "/dev/ttyS0"
*
* @return char pointer of device path
*/
std::string
getDevicePath()
{
std::string ret_val(mraa_uart_ow_get_dev_path(m_uart));
return ret_val;
}
/**
* Read a byte from the 1-wire bus
*
* @return the byte read
*/
uint8_t
readByte()
{
return mraa_uart_ow_read_byte(m_uart);
}
/**
* Write a byte to a 1-wire bus
*
* @param byte the byte to write to the bus
* @return the byte read back during the time slot
*/
uint8_t
writeByte(uint8_t byte)
{
return mraa_uart_ow_write_byte(m_uart, byte);
}
/**
* Write a bit to a 1-wire bus and read a bit corresponding to the
* time slot back. This is possible due to the way we wired the TX
* and RX together with a diode, forming a loopback.
*
* @param bit the bit to write to the bus
* @return the bit read back during the time slot
*/
bool
writeBit(bool bit)
{
uint8_t rv = mraa_uart_ow_bit(m_uart, (bit) ? 1 : 0);
return ((rv) ? true : false);
}
/**
* Send a reset pulse to the 1-wire bus and test for device presence
*
* @return one of the mraa::Result values
*/
mraa::Result
reset()
{
return (mraa::Result) mraa_uart_ow_reset(m_uart);
}
/**
* Begin a rom code search of the 1-wire bus. This function
* implements the 1-wire search algorithm. See the uart_ow.c example
* for an idea on how to use this function to identify all devices
* present on the bus.
*
* @param start true to start a search from scratch, false to
* continue a previously started search
* @param id the 8-byte rom code id of the current matched device when a
* device is found
* @return one of the mraa::Result values
*/
mraa::Result
search(bool start, uint8_t* id)
{
return (mraa::Result) mraa_uart_ow_rom_search(m_uart, (start) ? 1 : 0, id);
}
/**
* Begin a rom code search of the 1-wire bus. This function
* implements the 1-wire search algorithm. See the UartOW.cpp
* example for an idea on how to use this function to identify all
* devices present on the bus.
*
* @param start true to start a search from scratch, false to
* continue a previously started search
* @return an empty string if no [more] devices are found, or a
* string containing the 8-byte romcode of a detected device.
*/
std::string
search(bool start)
{
uint8_t id[MRAA_UART_OW_ROMCODE_SIZE];
mraa_result_t rv;
rv = mraa_uart_ow_rom_search(m_uart, (start) ? 1 : 0, id);
if (rv == MRAA_SUCCESS) {
// we found one
std::string idStr((char*) id, MRAA_UART_OW_ROMCODE_SIZE);
return idStr;
} else {
// failure, or end of search
return "";
}
}
/**
* Send a command byte to a device on the 1-wire bus
*
* @param command the command byte to send
* @param id the rom code id of the device to receive the command,
* NULL for all devices on the bus
* @return one of the mraa::Result values
*/
mraa::Result
command(uint8_t command, uint8_t* id)
{
return (mraa::Result) mraa_uart_ow_command(m_uart, command, id);
}
/**
* Send a command byte to a device on the 1-wire bus, supplying
* the id as a std::string
*
* @param command the command byte to send
* @param id std::string representing the code id of the device to
* receive the command, or an empty string for all devices on the
* bus. This string should be 8 bytes in size.
* @return one of the mraa::Result values
*/
mraa::Result
command(uint8_t command, std::string id)
{
if (id.empty() == 0)
return (mraa::Result) mraa_uart_ow_command(m_uart, command, NULL);
else {
if (id.size() != 8) {
// Only 8 byte romcodes are legal.
throw std::invalid_argument(std::string(__FUNCTION__) +
": id must be 8 bytes only");
}
return (mraa::Result) mraa_uart_ow_command(m_uart, command, (uint8_t*) id.c_str());
}
}
/**
* Perform a Dallas 1-wire compliant CRC8 computation on a buffer
*
* @param buffer the buffer containing the data
* @param length the length of the buffer
* @return the computed CRC
*/
uint8_t
crc8(uint8_t* buffer, uint16_t length)
{
return mraa_uart_ow_crc8(buffer, length);
}
/**
* Perform a Dallas 1-wire compliant CRC8 computation on a
* std::string based buffer
*
* @param buffer std::string buffer containing the data
* @return the computed CRC
*/
uint8_t
crc8(std::string buffer)
{
return mraa_uart_ow_crc8((uint8_t*) buffer.c_str(), buffer.size());
}
private:
mraa_uart_ow_context m_uart;
};
}