api/maa/pwm.h

   1 /*
   2  * Author: Thomas Ingleby <thomas.c.ingleby@intel.com>
   3  * Copyright (c) 2014 Intel Corporation.
   4  *
   5  * Permission is hereby granted, free of charge, to any person obtaining
   6  * a copy of this software and associated documentation files (the
   7  * "Software"), to deal in the Software without restriction, including
   8  * without limitation the rights to use, copy, modify, merge, publish,
   9  * distribute, sublicense, and/or sell copies of the Software, and to
  10  * permit persons to whom the Software is furnished to do so, subject to
  11  * the following conditions:
  12  *
  13  * The above copyright notice and this permission notice shall be
  14  * included in all copies or substantial portions of the Software.
  15  *
  16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  17  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  18  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  19  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  20  * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  21  * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  22  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  23  */
  24
  25 #pragma once
  26
  27 /**
  28  * @file
  29  * @brief Pulse Width Modulation module
  30  *
  31  * PWM is the Pulse Width Modulation interface to libmaa. It allows the
  32  * generation of a signal on a pin. Some boards may have higher or lower levels
  33  * of resolution so make sure you check the board & pin you are using before
  34  * hand.
  35  *
  36  * @snippet cycle-pwm3.c Interesting
  37  */
  38
  39 #ifdef __cplusplus
  40 extern "C" {
  41 #endif
  42
  43 #include <stdio.h>
  44 #include <fcntl.h>
  45
  46 #include "common.h"
  47
  48 typedef struct _pwm* maa_pwm_context;
  49
  50 /**
  51  * Initialise pwm_context, uses board mapping
  52  *
  53  * @param pin The PWM PIN
  54  * @return pwm context or NULL
  55  */
  56 maa_pwm_context maa_pwm_init(int pin);
  57
  58 /**
  59  * Initialise pwm_context, raw mode
  60  *
  61  * @param chipid The chip inwhich the PWM is under in SYSFS
  62  * @param pin The PWM PIN.
  63  * @return pwm context or NULL
  64  */
  65 maa_pwm_context maa_pwm_init_raw(int chipid, int pin);
  66
  67 /**
  68  * Set the ouput duty-cycle percentage, as a float
  69  *
  70  * @param dev The Pwm context to use
  71  * @param percentage A floating-point value representing percentage of output.
  72  *    The value should lie between 0.0f (representing on 0%) and 1.0f
  73  *    Values above or below this range will be set at either 0.0f or 1.0f
  74  * @return Result of operation
  75  */
  76 maa_result_t maa_pwm_write(maa_pwm_context dev, float percentage);
  77
  78 /**
  79  * Read the ouput duty-cycle percentage, as a float
  80  *
  81  * @param dev The Pwm context to use
  82  * @return percentage A floating-point value representing percentage of output.
  83  *    The value should lie between 0.0f (representing on 0%) and 1.0f
  84  *    Values above or below this range will be set at either 0.0f or 1.0f
  85  */
  86 float maa_pwm_read(maa_pwm_context dev);
  87
  88 /**
  89  * Set the PWM period as seconds represented in a float
  90  *
  91  * @param dev The Pwm context to use
  92  * @param seconds Period represented as a float in seconds
  93  * @return Result of operation
  94  */
  95 maa_result_t maa_pwm_period(maa_pwm_context dev, float seconds);
  96
  97 /**
  98  * Set period, milliseconds.
  99  *
 100  * @param dev The Pwm context to use
 101  * @param ms Milliseconds for period
 102  * @return Result of operation
 103  */
 104 maa_result_t maa_pwm_period_ms(maa_pwm_context dev, int ms);
 105
 106 /**
 107  * Set period, microseconds
 108  *
 109  * @param dev The Pwm context to use
 110  * @param us Microseconds as period
 111  * @return Result of operation
 112  */
 113 maa_result_t maa_pwm_period_us(maa_pwm_context dev, int us);
 114
 115 /**
 116  * Set pulsewidth, As represnted by seconds in a (float)
 117  *
 118  * @param dev The Pwm context to use
 119  * @param seconds The duration of a pulse
 120  * @return Result of operation
 121  */
 122 maa_result_t maa_pwm_pulsewidth(maa_pwm_context dev, float seconds);
 123
 124 /**
 125  * Set pulsewidth, milliseconds
 126  *
 127  * @param dev The Pwm context to use
 128  * @param ms Milliseconds for pulsewidth
 129  * @return Result of operation
 130  */
 131 maa_result_t maa_pwm_pulsewidth_ms(maa_pwm_context dev, int ms);
 132
 133 /**
 134  * Set pulsewidth, microseconds
 135  *
 136  * @param dev The Pwm context to use
 137  * @param us Microseconds for pulsewidth
 138  * @return Result of operation
 139  */
 140 maa_result_t maa_pwm_pulsewidth_us(maa_pwm_context dev, int us);
 141
 142 /**
 143  * Set the enable status of the PWM pin. None zero will assume on with output being driven.
 144  *   and 0 will disable the output.
 145  *
 146  * @param dev The pwm context to use
 147  * @param enable Toggle status of pin
 148  * @return Result of operation.
 149  */
 150 maa_result_t maa_pwm_enable(maa_pwm_context dev, int enable);
 151
 152 /**
 153  * Change ownership of context
 154  *
 155  * @param dev the context
 156  * @param owner Ownership boolean
 157  * @return Result of operation
 158  */
 159 maa_result_t maa_pwm_owner(maa_pwm_context dev, maa_boolean_t owner);
 160
 161 /**
 162  * Close and unexport the PWM pin
 163  *
 164  * @param dev The pwm context to use
 165  * @return Result of operation
 166  */
 167 maa_result_t maa_pwm_close(maa_pwm_context dev);
 168
 169 #ifdef __cplusplus
 170 }
 171 #endif