File content as of revision 9:b6218dc218ad:

/*
 * Copyright 2014, ACKme Networks
 * All Rights Reserved.
 *
 * This is UNPUBLISHED PROPRIETARY SOURCE CODE of ACKme Networks;
 * the contents of this file may not be disclosed to third parties, copied
 * or duplicated in any form, in whole or in part, without the prior
 * written permission of ACKme Networks.
 */

#pragma once

#include "WiconnectTypes.h"


#include "types/LogFunc.h"
#include "types/ReaderFunc.h"
#include "types/Callback.h"
#include "types/QueuedCommand.h"
#include "types/CommandQueue.h"
#include "types/TimeoutTimer.h"
#include "types/PeriodicTimer.h"
#include "types/Gpio.h"
#include "types/WiconnectSerial.h"

#include "NetworkInterface.h"
#include "SocketInterface.h"
#include "FileInterface.h"


#ifdef WICONNECT_ENABLE_MALLOC
/// These are optional arguments for host specific malloc/free
#define WICONNECT_MALLOC_ARGS , void* (*malloc_)(size_t) = WICONNECT_DEFAULT_MALLOC, void (*free_)(void*) = WICONNECT_DEFAULT_FREE
#else
#define WICONNECT_MALLOC_ARGS
#endif


namespace wiconnect {


/**
 *
 *
 * The root WiConnect library class. This class
 * inheriets all WiConnect functionality.
 *
 * This class is implemented as a 'singleton'. This means it
 * only needs to be instantiated once. Subsequent class may either
 * use the class instance or the static function: @ref Wiconnect::getInstance()
 *
 */
class Wiconnect : public NetworkInterface,
                  public SocketInterface,
                  public FileInterface
{
public:

    /**
     *
     *
     * WiConnect class constructor
     *
     * @note This should only be called once within a program as the WiConnect
     *       library is implemented as a singleton.
     *
     * @note If this constructor is used, then all commands must be supplied with an external response buffer.
     *       This means most the API functions will not work as they use the internal buffer.
     *       It's recommended to use the other constructor that supplies an internal buffer. See @ref setting_alloc
     *
     * @param[in] serialConfig The serial (i.e. UART) configuration connected to a WiConnect module.
     * @param[in] reset Optional, The pin connected to the WiConnect module reset signal. Default: No connection
     * @param[in] wake Optional, The pin connected to the WiConnect module wake signal. Default: No connection
     * @param[in] nonBlocking Optional, indicates if the API blocking mode. See @ref setting_blocking_modes
     */
    Wiconnect(const SerialConfig &serialConfig, Pin reset = PIN_NC, Pin wake = PIN_NC, bool nonBlocking = WICONNECT_DEFAULT_NONBLOCKING WICONNECT_MALLOC_ARGS);

    /**
     *
     *
     * WiConnect class constructor
     *
     * @note This should only be called once within a program as the WiConnect
     *       library is implemented as a singleton.
     *
     * @note This is the recommended construstor as it supplies the WiConnect library with an
     *       internal buffer. Most API calls require the internal buffer.
     *
     * @param[in] serialConfig The serial (i.e. UART) configuration connected to a WiConnect module.
     * @param[in] internalBuffer Optional, a user allocated buffer. See @ref setting_alloc
     * @param[in] internalBufferSize The size of the internal buffer. If internalBuffer is NULL, then this size will be dynamically allocated. See @ref setting_alloc
     * @param[in] reset Optional, The pin connected to the WiConnect module reset signal. Default: No connection
     * @param[in] wake Optional, The pin connected to the WiConnect module wake signal. Default: No connection
     * @param[in] nonBlocking Optional, indicates if the API blocking mode. See @ref setting_blocking_modes
     */
    Wiconnect(const SerialConfig &serialConfig, void *internalBuffer, int internalBufferSize, Pin reset = PIN_NC, Pin wake = PIN_NC, bool nonBlocking = WICONNECT_DEFAULT_NONBLOCKING WICONNECT_MALLOC_ARGS);
    ~Wiconnect();

    /**
     * @ingroup  api_core_misc
     *
     * Get instance of previously instantiated Wiconnect Library
     *
     * @return Pointer to instance of @ref Wiconnect Library.
     */
    static Wiconnect* getInstance();

    /**
     * @ingroup  api_core_misc
     *
     * Initialize library and communication link with WiConnect WiFi module.
     *
     * @note This function is always blocking regardless of configured mode.
     *
     * @param[in] bringNetworkUp Flag indicating if the module should try to bring the network up upon initialization.
     * @return Result of initialization. See @ref WiconnectResult
     */
    WiconnectResult init(bool bringNetworkUp);

    /**
     * @ingroup  api_core_misc
     *
     * De-initialize library.
     */
    void deinit();

    /**
     * @ingroup api_core_misc
     *
     * Return TRUE if library is able to communicated with WiConnect WiFi module.
     * FALSE else.
     *
     * @return TRUE if library can communicate with WiFi module, FALSE else.
     */
    bool isInitialized();

    /**
     * @ingroup api_core_misc
     *
     * Toggle the WiConnect WiFi module reset signal.
     *
     * @note This only resets the module if the library was instantiated with the 'reset' pin
     *       parameter in the Wiconnect::Wiconnect constructor.
     * @note This method is always blocking. A small (1s) delay is added to ensure the module
     *       has returned from reset and ready.
     *
     * @return Result of method. See @ref WiconnectResult
     */
    WiconnectResult reset();

    /**
     * @ingroup api_core_misc
     *
     * Toggle the WiConnect WiFi moduel wakeup signal.
     *
     * @note This only wakes the module if the library was instantiated with the 'wake' pin
     *       parameter in the Wiconnect::Wiconnect constructor.
     * @note This method is always blocking.
     *
     * @return Result of method. See @ref WiconnectResult
     */
    WiconnectResult wakeup();

    /**
     * @ingroup api_core_misc
     *
     * Flush any received data in serial RX buffer and terminate any commands on WiConnect WiFi module.
     */
    void flush(int delayMs = 500);

    /**
     * @ingroup api_core_misc
     *
     * Return current version of WiConnect WiFi module.
     */
    WiconnectResult getVersion(char *versionBuffer = NULL, int versionBufferSize = 0, const Callback &completeCallback = Callback());

    /**
     * @ingroup api_core_send_command
     *
     * @brief Send command to WiConnect WiFi module
     * Refer to @ref send_command_desc for more info
     */
    WiconnectResult sendCommand(const Callback &completeCallback, char *responseBuffer, int responseBufferLen,
                                int timeoutMs, const ReaderFunc &reader, void *user, const char *cmd, va_list vaList);
    /**
     * @ingroup api_core_send_command
     *
     * @brief Send command to WiConnect WiFi module
     * Refer to @ref send_command_desc for more info
     */
    WiconnectResult sendCommand(char *responseBuffer, int responseBufferLen, int timeoutMs, const ReaderFunc &reader,
                                void *user, const char *cmd, va_list vaList);

    /**
     * @ingroup api_core_send_command
     *
     * @brief Send command to WiConnect WiFi module
     * Refer to @ref send_command_desc for more info
     *
     * @note This method supports variable arguments
     *
     */
    WiconnectResult sendCommand(char *responseBuffer, int responseBufferLen, int timeoutMs, const ReaderFunc &reader,
                                void *user, const char *cmd, ...);

    /**
     * @ingroup api_core_send_command
     *
     * @brief Send command to WiConnect WiFi module
     * Refer to @ref send_command_desc for more info
     *
     * @note This method supports variable arguments
     *
     */
    WiconnectResult sendCommand( int timeoutMs, const ReaderFunc &reader, void *user, const char *cmd, ...);

    /**
     * @ingroup api_core_send_command
     *
     * @brief Send command to WiConnect WiFi module
     * Refer to @ref send_command_desc for more info
     *
     * @note This method supports variable arguments
     *
     */
    WiconnectResult sendCommand(const ReaderFunc &reader, void *user, const char *cmd, ...);

    /**
     * @ingroup api_core_send_command
     *
     * @brief Send command to WiConnect WiFi module
     * Refer to @ref send_command_desc for more info
     *
     * @note This method supports variable arguments
     *
     */
    WiconnectResult sendCommand(char *responseBuffer, int responseBufferLen,  int timeoutMs, const char *cmd, ...);

    /**
     * @ingroup api_core_send_command
     *
     * @brief Send command to WiConnect WiFi module
     * Refer to @ref send_command_desc for more info
     *
     * @note This method supports variable arguments
     *
     */
    WiconnectResult sendCommand(const Callback &completeCallback, char *responseBuffer, int responseBufferLen, const char *cmd, ...);

    /**
     * @ingroup api_core_send_command
     *
     * @brief Send command to WiConnect WiFi module
     * Refer to @ref send_command_desc for more info
     *
     * @note This method supports variable arguments
     *
     */
    WiconnectResult sendCommand(char *responseBuffer, int responseBufferLen, const char *cmd, ...);

    /**
     * @ingroup api_core_send_command
     *
     * @brief Send command to WiConnect WiFi module
     * Refer to @ref send_command_desc for more info
     *
     * @note This method supports variable arguments
     *
     */
    WiconnectResult sendCommand(const Callback &completeCallback, const char *cmd, ...);

    /**
     * @ingroup api_core_send_command
     *
     * @brief Send command to WiConnect WiFi module
     * Refer to @ref send_command_desc for more info
     *
     * @note This method supports variable arguments
     *
     */
    WiconnectResult sendCommand(const char *cmd, ...);

    /**
     * @ingroup api_core_send_command
     *
     * @brief Send command to WiConnect WiFi module
     * Refer to @ref send_command_desc for more info
     *
     * @note This method supports variable arguments
     *
     */
    WiconnectResult sendCommand(const Callback &completeCallback, int timeoutMs, const char *cmd, ...);

    /**
     * @ingroup api_core_send_command
     *
     * @brief Send command to WiConnect WiFi module
     * Refer to @ref send_command_desc for more info
     *
     * @note This method supports variable arguments
     *
     */
    WiconnectResult sendCommand(int timeoutMs, const char *cmd, ...);

    /**
     * @ingroup api_core_send_command
     *
     * @brief Send command to WiConnect WiFi module
     * Refer to @ref send_command_desc for more info
     *
     */
    WiconnectResult sendCommand(const char *cmd, va_list vaList);

    /**
     * @ingroup api_core_misc
     *
     * When the WiConnect WiFi module returns a response, it contains a
     * response code in the header. This function converts the previous response code
     * to a readable string.
     */
    const char* getLastCommandResponseCodeStr();

    /**
     * @ingroup api_core_misc
     *
     * Return the length in bytes of the previous response.
     */
    uint16_t getLastCommandResponseLength();

    /**
     * @ingroup api_core_misc
     *
     * Return pointer to internal response buffer.
     */
    char* getResponseBuffer();

    /**
     * @ingroup api_core_misc
     *
     * Helper method to convert previous response to uint32
     */
    WiconnectResult responseToUint32(uint32_t *uint32Ptr);

    /**
     * @ingroup api_core_misc
     *
     * Helper method to convert previous response to int32
     */
    WiconnectResult responseToInt32(int32_t *int32Ptr);

    /**
     * @ingroup api_core_send_command
     *
     * Check the status of the currently executing command.
     *
     * Refer to @ref WiconnectResult for more information about the return code.
     *
     * @note This command is only applicable for non-blocking mode. Refer to @ref setting_blocking_modes.
     */
    WiconnectResult checkCurrentCommand();

    /**
     * @ingroup api_core_send_command
     *
     * Stop the currently executing command.
     *
     * @note This command is only applicable for non-blocking mode. Refer to @ref setting_blocking_modes.
     */
    void stopCurrentCommand();

    /**
     * @ingroup api_core_settings
     *
     * Sets the default maximum time an API method may execute before
     * terminating and return a timeout error code.
     *
     * @note All API method (execpt some sendCommand()) use this default value.
     */
    void setCommandDefaultTimeout(int timeoutMs);

    /**
     * @ingroup api_core_settings
     *
     * Returns the current default maximum API execution time.
     */
    int getCommandDefaultTimeout();

    /**
     * @ingroup api_core_settings
     *
     * Sets a mapping function used to convert from a host Pin to WiConnect WiFi module GPIO.
     */
    void setPinToGpioMapper(PinToGpioMapper mapper);

    /**
     * @ingroup api_core_settings
     *
     * Sets callback function used to debug WiConnect WiFi module RX/TX serial data.
     */
    void setDebugLogger(LogFunc logFunc);

    /**
     * @ingroup api_core_settings
     *
     * Sets callback used when Wiconnect Library hits and internal assertion.
     *
     * @note This is mainly for debugging. There's nothing the callback can do to fix the assertion.
     */
    void setAssertLogger(LogFunc assertLogFunc);

#ifdef WICONNECT_ASYNC_TIMER_ENABLED
    /**
     * @ingroup api_core_send_command
     *
     * Add user command to be executed asynchronously.
     *
     */
    WiconnectResult enqueueCommand(QueuedCommand *command, const Callback &commandCompleteHandler = Callback());

    /**
     * @ingroup api_core_settings
     *
     * Set the period at which an asynchronous command should be processed.
     */
    void setCommandProcessingPeriod(uint32_t periodMs);
#endif


    /**
     * @ingroup conversion_util
     *
     * Converts a @ref WiconnectResult to string representation.
     */
    static const char* getWiconnectResultStr(WiconnectResult wiconnectResult);

protected:

#ifdef WICONNECT_ENABLE_MALLOC
    void* (*_malloc)(size_t);
    void (*_free)(void *);
    friend class QueuedCommand;
    friend class WiconnectSerial;
    friend class ScanResult;
    friend class ScanResultList;
    friend class Socket;
    friend class File;
#endif

    wiconnect::WiconnectSerial serial;
    wiconnect::Gpio resetGpio;
    wiconnect::Gpio wakeGpio;

    volatile bool commandExecuting;
    bool initialized;
    bool nonBlocking;

    PinToGpioMapper pinToGpioMapper;

    char *internalBuffer;
    int internalBufferSize;
    bool internalBufferAlloc;
    uint8_t internalProcessingState;
    void *currentCommandId;

    wiconnect::TimeoutTimer timeoutTimer;
    int defaultTimeoutMs;

    uint8_t commandHeaderBuffer[32];
    char commandFormatBuffer[WICONNECT_MAX_CMD_SIZE];
    uint8_t commandContext[96];

    void prepare(void *internalBuffer, int internalBufferSize, bool nonBlocking);
    WiconnectResult inline receiveResponse();
    WiconnectResult inline receivePacket();
    void issueCommandCallback(WiconnectResult result);

    LogFunc debugLogger;
    LogFunc assertLogger;
    void debugLog(const char *msg, ...);

#ifdef WICONNECT_ASYNC_TIMER_ENABLED
    wiconnect::PeriodicTimer commandProcessorTimer;
    uint32_t commandProcessingPeriod;
    CommandQueue commandQueue;
    wiconnect::QueuedCommand *currentQueuedCommand;

    void commandProcessingTimerHandler(void);
    void processNextQueuedCommand();
    void checkQueuedCommandTimeout();
#endif

    friend class NetworkInterface;
    friend class SocketInterface;
    friend class FileInterface;
};

}