api/mraa/common.h

   1 /*
   2  * Author: Brendan Le Foll <brendan.le.foll@intel.com>
   3  * Author: Thomas Ingleby <thomas.c.ingleby@intel.com>
   4  * Copyright © 2014 Intel Corporation
   5  *
   6  * Permission is hereby granted, free of charge, to any person obtaining a copy
   7  * of this software and associated documentation files (the "Software"), to
   8  * deal in the Software without restriction, including without limitation the
   9  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  10  * sell copies of the Software, and to permit persons to whom the Software is
  11  * furnished to do so, subject to the following conditions:
  12  *
  13  * The above copyright notice and this permission notice shall be included in
  14  * all copies or substantial portions of the Software.
  15  *
  16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  19  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  21  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  22  * IN THE SOFTWARE.
  23  */
  24
  25 #pragma once
  26
  27 #include "types.h"
  28
  29 #define MRAA_PLATFORM_NAME_MAX_SIZE 64
  30
  31 /** @file
  32  *
  33  * This file defines the basic shared values for libmraa
  34  */
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 /**
  41  * MRAA boolean type
  42  * 1 For TRUE
  43  */
  44 typedef unsigned int mraa_boolean_t;
  45
  46 /**
  47  * A bitfield representing the capabilities of a pin.
  48  */
  49 typedef struct {
  50     /*@{*/
  51     mraa_boolean_t valid:1;     /**< Is the pin valid at all */
  52     mraa_boolean_t gpio:1;      /**< Is the pin gpio capable */
  53     mraa_boolean_t pwm:1;       /**< Is the pin pwm capable */
  54     mraa_boolean_t fast_gpio:1; /**< Is the pin fast gpio capable */
  55     mraa_boolean_t spi:1;       /**< Is the pin spi capable */
  56     mraa_boolean_t i2c:1;       /**< Is the pin i2c capable */
  57     mraa_boolean_t aio:1;       /**< Is the pin analog input capable */
  58     mraa_boolean_t uart:1;       /**< Is the pin uart capable */
  59     /*@}*/
  60 } mraa_pincapabilities_t;
  61
  62 /**
  63  * A Structure representing a multiplexer and the required value
  64  */
  65 typedef struct {
  66     /*@{*/
  67     unsigned int pin;   /**< Raw GPIO pin id */
  68     unsigned int value; /**< Raw GPIO value */
  69     /*@}*/
  70 } mraa_mux_t;
  71
  72 typedef struct {
  73     mraa_boolean_t complex_pin:1;
  74     mraa_boolean_t output_en:1;
  75     mraa_boolean_t output_en_high:1;
  76     mraa_boolean_t pullup_en:1;
  77     mraa_boolean_t pullup_en_hiz:1;
  78 } mraa_pin_cap_complex_t;
  79
  80 typedef struct {
  81     /*@{*/
  82     unsigned int pinmap; /**< sysfs pin */
  83     unsigned int parent_id; /** parent chip id */
  84     unsigned int mux_total; /** Numfer of muxes needed for operation of pin */
  85     mraa_mux_t mux[6]; /** Array holding information about mux */
  86     unsigned int output_enable; /** Output Enable GPIO, for level shifting */
  87     unsigned int pullup_enable; /** Pull-Up enable GPIO, inputs */
  88     mraa_pin_cap_complex_t complex_cap;
  89     /*@}*/
  90 } mraa_pin_t;
  91
  92 typedef struct {
  93     /*@{*/
  94     char mem_dev[32]; /**< Memory device to use /dev/uio0 etc */
  95     unsigned int mem_sz; /** Size of memory to map */
  96     unsigned int bit_pos; /** Position of value bit */
  97     mraa_pin_t gpio; /** GPio context containing none mmap info */
  98     /*@}*/
  99 } mraa_mmap_pin_t;
 100
 101 /**
 102  * A Structure representing a physical Pin.
 103  */
 104 typedef struct {
 105     /*@{*/
 106     char name[8];                      /**< Pin's real world name */
 107     mraa_pincapabilities_t capabilites; /**< Pin Capabiliites */
 108     mraa_pin_t gpio; /**< GPIO structure */
 109     mraa_pin_t pwm;  /**< PWM structure */
 110     mraa_pin_t aio;  /**< Anaglog Pin */
 111     mraa_mmap_pin_t mmap; /**< GPIO through memory */
 112     mraa_pin_t i2c;  /**< i2c bus/pin */
 113     mraa_pin_t spi;  /**< spi bus/pin */
 114     mraa_pin_t uart;  /**< uart module/pin */
 115     /*@}*/
 116 } mraa_pininfo_t;
 117
 118 /**
 119  * A Structure representing the physical properties of a i2c bus.
 120  */
 121 typedef struct {
 122     /*@{*/
 123     unsigned int bus_id; /**< ID as exposed in the system */
 124     unsigned int scl; /**< i2c SCL */
 125     unsigned int sda; /**< i2c SDA */
 126     /*@}*/
 127 } mraa_i2c_bus_t;
 128
 129 /**
 130  * A Structure representing the physical properties of a spi bus.
 131  */
 132 typedef struct {
 133     /*@{*/
 134     unsigned int bus_id; /**< The Bus ID as exposed to the system. */
 135     unsigned int slave_s; /**< Slave select */
 136     mraa_boolean_t three_wire; /**< Is the bus only a three wire system */
 137     unsigned int sclk; /**< Serial Clock */
 138     unsigned int mosi; /**< Master Out, Slave In. */
 139     unsigned int miso; /**< Master In, Slave Out. */
 140     unsigned int cs; /**< Chip Select, used when the board is a spi slave */
 141     /*@}*/
 142 } mraa_spi_bus_t;
 143
 144 /**
 145  * A Structure representing a uart device.
 146  */
 147 typedef struct {
 148     /*@{*/
 149     unsigned int index; /**< ID as exposed in the system */
 150     int rx; /**< uart rx */
 151     int tx; /**< uart tx */
 152     const char* device_path; /**< To store "/dev/ttyS1" for example */
 153     /*@}*/
 154 } mraa_uart_dev_t;
 155
 156 /**
 157  * A Structure representing a platform/board.
 158  */
 159 typedef struct {
 160     /*@{*/
 161     unsigned int phy_pin_count; /**< The Total IO pins on board */
 162     unsigned int gpio_count; /**< GPIO Count */
 163     unsigned int aio_count;  /**< Analog side Count */
 164     unsigned int i2c_bus_count; /**< Usable i2c Count */
 165     mraa_i2c_bus_t  i2c_bus[12]; /**< Array of i2c */
 166     unsigned int def_i2c_bus; /**< Position in array of default i2c bus */
 167     unsigned int spi_bus_count; /**< Usable spi Count */
 168     mraa_spi_bus_t spi_bus[12];       /**< Array of spi */
 169     unsigned int def_spi_bus; /**< Position in array of defult spi bus */
 170     unsigned int adc_raw; /**< ADC raw bit value */
 171     unsigned int adc_supported; /**< ADC supported bit value */
 172     unsigned int def_uart_dev; /**< Position in array of defult uart */
 173     unsigned int uart_dev_count; /**< Usable spi Count */
 174     mraa_uart_dev_t uart_dev[6]; /**< Array of UARTs */
 175     int pwm_default_period; /**< The default PWM period is US */
 176     int pwm_max_period; /**< Maximum period in us */
 177     int pwm_min_period; /**< Minimum period in us */
 178     unsigned int platform_name_length; /**< Platform Name length */
 179     char* platform_name; /**< Platform Name pointer */
 180     mraa_pininfo_t* pins;     /**< Pointer to pin array */
 181     /*@}*/
 182 } mraa_board_t;
 183
 184 /**
 185  * Initialise MRAA
 186  *
 187  * Detects running platform and attempts to use included pinmap
 188  *
 189  * @return Result of operation
 190  */
 191 #if (defined SWIGPYTHON) || (defined SWIG)
 192 mraa_result_t mraa_init();
 193 #else
 194 // this sets a compiler attribute (supported by GCC & clang) to have mraa_init()
 195 // be called as a constructor make sure your libc supports this!  uclibc needs
 196 // to be compiled with UCLIBC_CTOR_DTOR
 197 mraa_result_t mraa_init() __attribute__((constructor));
 198 #endif
 199
 200 /**
 201  * De-Initilise MRAA
 202  *
 203  * This is not a strict requirement but useful to test memory leaks and for
 204  * people who like super clean code. If dynamically loading & unloading
 205  * libmraa you need to call this before unloading the library.
 206  */
 207 void mraa_deinit();
 208
 209 /**
 210  * Checks if a pin is able to use the passed in mode.
 211  *
 212  * @param pin Physical Pin to be checked.
 213  * @param mode the mode to be tested.
 214  * @return boolean if the mode is supported, 0=false.
 215  */
 216 mraa_boolean_t mraa_pin_mode_test(int pin, mraa_pinmodes_t mode);
 217
 218 /**
 219  * Check the board's  bit size when reading the value
 220  *
 221  * @return raw bits being read from kernel module. zero if no ADC
 222  */
 223 unsigned int mraa_adc_raw_bits();
 224
 225 /**
 226  * Return value that the raw value should be shifted to. Zero if no ADC
 227  *
 228  * @return return actual bit size the adc value should be understood as.
 229  */
 230 unsigned int mraa_adc_supported_bits();
 231
 232 /**
 233  * Sets the log level to use from 0-7 where 7 is very verbose. These are the
 234  * syslog log levels, see syslog(3) for more information on the levels.
 235  *
 236  * @return Result of operation
 237  */
 238 mraa_result_t mraa_set_log_level(int level);
 239
 240 /**
 241  * Return the Platform's Name, If no platform detected return "Unknown"
 242  *
 243  * @return platform name
 244  */
 245 char* mraa_get_platform_name();
 246
 247 /**
 248  * This function attempts to set the mraa process to a given priority and the
 249  * scheduler to SCHED_RR. Highest * priority is typically 99 and minimum is 0.
 250  * This function * will set to MAX if * priority is > MAX. Function will return
 251  * -1 on failure.
 252  *
 253  * @param priority Value from typically 0 to 99
 254  * @return The priority value set
 255  */
 256 int mraa_set_priority(const unsigned int priority);
 257
 258 /** Get the version string of mraa autogenerated from git tag
 259  *
 260  * The version returned may not be what is expected however it is a reliable
 261  * number associated with the git tag closest to that version at build time
 262  *
 263  * @return version string from version.h
 264  */
 265 const char* mraa_get_version();
 266
 267 /**
 268  * Print a textual representation of the mraa_result_t
 269  *
 270  * @param result the result to print
 271  */
 272 void mraa_result_print(mraa_result_t result);
 273
 274 /**
 275  * Get platform type, board must be initialised.
 276  *
 277  * @return mraa_platform_t Platform type enum
 278  */
 279 mraa_platform_t mraa_get_platform_type();
 280
 281 #ifdef __cplusplus
 282 }
 283 #endif