/**
 * Copyright 2025 Derya Y. (iiot2k@gmail.com).
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use node file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 **/

// for detail see API.md

// gpio mode constans
export const GPIO_MODE_INPUT_NOPULL: number;   // 0 -> floating input
export const GPIO_MODE_INPUT_PULLDOWN: number; // 1 -> input with pull down resistor
export const GPIO_MODE_INPUT_PULLUP: number;   // 2 -> input with pull up resistor
export const GPIO_MODE_OUTPUT: number;         // 3 -> output
export const GPIO_MODE_OUTPUT_SOURCE: number;  // 4 -> output source, Hi-Z on 0, connect to +3.3V on 1
export const GPIO_MODE_OUTPUT_SINK: number;    // 5 -> output sink, Hi-Z on 0, connect to ground on 1

// pwm constans
export const DUTY_MIN: number; // 0 -> min. duty cycle (%)
export const DUTY_MAX: number; // 100 -> max. duty cycle (%)
export const FREQ_MIN: number; // 1 -> min. pwm frequency (Hz)
export const FREQ_MAX: number; // 1000 -> max. pwm frequency (Hz)

/**
 * returns error text on failure.
 * @returns error text
 */
export function error_text(): string;

/**
 * returns addon version.
 * @returns version
 */
export function version(): string;

/**
 * inits gpio.
 * 
 * @param pin - gpio pin number 0..27
 * @param mode - constant GPIO_MODE_..
 * @param setval - debounce time in us for input, state to set 0/1 or true/false for output
 * @returns true on ok, false on error
 * 
 * @note setval 0 for inputs disables debounce
 */
export function init_gpio(
    pin: number, 
    mode: number, 
    setval: number|boolean, 
 ): boolean;

 /**
 * deinits gpio.
 * 
 * @param pin - gpio pin number 0..27
 * @returns true on ok, false on error
 * 
 * @note GPIO pin is deinitialized when the program ends
 * @note stops also blink
 */
export function deinit_gpio(pin: number): boolean;

/**
 * gets gpio state as boolean.
 * 
 * @param pin - gpio pin number 0..27
 * @returns true/false, undefined on error
 */
export function get_gpio(pin: number) : boolean;
 
/**
 * gets gpio state as number.
 * 
 * @param pin - gpio pin number 0..27
 * @returns 0/1, undefined on error
 */
export function get_gpio_num(pin: number): number;
 
/**
 * sets gpio state of output.
 * 
 * @param pin - gpio pin number 0..27
 * @param mode - constant GPIO_MODE_..
 * @param value - state to set 0/1 or true/false
 * @returns true on ok, false on error
 */
export function set_gpio(pin:number, value: number|boolean): boolean;
 
/**
 * toggle gpio output.
 * 
 * @param pin - gpio pin number 0..27
 * @returns true on ok, false on error
 */
export function toggle_gpio(pin: number): boolean;

/**
 * blink gpio output.
 * 
 * @param pin - gpio pin number 0..27
 * @param period blink period in ms (1..), 0 stops blink
 * @returns true on ok, false on error
 */
export function blink_gpio(pin: number, period: number): boolean;
 
/**
 * stop blink gpio output.
 * 
 * @param pin - gpio pin number 0..27
 * @returns true on ok, false on error
 * 
 * @note call of read/write/toggle/pulse/pwm functions stops also blink
 */
export function stop_blink_gpio(pin: number): boolean;

/**
 * pulse gpio output.
 * 
 * @param pin - gpio pin number 0..27
 * @param period pulse period in ms (1..), 0 stops pulse
 * @returns true on ok, false on error
 */
export function pulse_gpio(pin: number, period: number): boolean;
 
/**
 * stop pulse gpio output.
 * 
 * @param pin - gpio pin number 0..27
 * @returns true on ok, false on error
 * 
 * @note call of read/write/toggle/blink/pwm functions stops also pulse
 */
export function stop_pulse_gpio(pin: number): boolean;

/**
 * pwm gpio output.
 * 
 * @param pin - gpio pin number 0..27
 * @param frequency pwm frequency in Hz (1..FREQ_MAX), 0 stops pwm
 * @param dutycycle pwm dutycycle in % (0..100), 0 turns output off, 100 turns output on
 * @returns true on ok, false on error
 */
export function pwm_gpio(pin: number, frequency: number, dutycycle: number): boolean;
 
/**
 * stop pwm gpio output.
 * 
 * @param pin - gpio pin number 0..27
 * @returns true on ok, false on error
 * 
 * @note call of read/write/toggle/blink/pulse functions stops also pwm
 */
export function stop_pwm_gpio(pin: number): boolean;

/**
 * returns pwm frequency.
 * if pwm not started default frequency is returned (400Hz)
 * 
 * @param pin - gpio pin number 0..27
 * @returns pwm frequency in Hz, undefined on error
 */
export function get_pwm_frequency(pin: number): number;

/**
 * returns pwm duty cycle.
 * if pwm not started default duty cycle is returned (50%)
 * 
 * @param pin - gpio pin number 0..27
 * @returns duty cycle in %, undefined on error
 */
export function get_pwm_dutycycle(pin: number): number;