EsmacatShield.h

00001 /**
00002   Copyright (c) 2020 https://www.esmacat.com/
00003 
00004   Licensed under the Apache License, Version 2.0 (the "License");
00005   you may not use this file except in compliance with the License.
00006   You may obtain a copy of the License at
00007 
00008     http://www.apache.org/licenses/LICENSE-2.0
00009 
00010   Unless required by applicable law or agreed to in writing, software
00011   distributed under the License is distributed on an "AS IS" BASIS,
00012   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013   See the License for the specific language governing permissions and
00014   limitations under the License.
00015 
00016   EsmacatShield.h - Library for using EtherCAT Arduino Shield by Esmacat(EASE).
00017   Created by Esmacat, 01/22/2020
00018   
00019 *******************************************************************************
00020 * @file EsmacatShield.h
00021 *******************************************************************************
00022 */
00023 
00024 
00025 #ifndef EsmacatShield_h
00026 #define EsmacatShield_h
00027 
00028 #include "mbed.h"
00029 
00030 #define EASE_READ_REG        0B00000000
00031 #define EASE_WRITE_REG       0B10000000
00032 #define EASE_SINGLE_SHOT     0B10111111
00033 #define EASE_LED_ON          0B00000100
00034 #define EASE_LED_OFF         0B11111011
00035 
00036 
00037 /**
00038 * @brief This is a driver code for EASE with form factor of Arduino 
00039 *        UNO shields. This shield communicates with the base board via SPI.
00040 *
00041 * @version 1.0
00042 *
00043 * @details EASE stacks onto Arduino-like boards (a.k.a Base board). 
00044 *  The Base board can read and write registers on EASE via SPI.
00045 *  The same registers can also be written and read by an EtherCAT master via a 
00046 *  standard EtherCAT protocol. Multiple EASE boards can be connected with 
00047 *  Ethernet cables with a daisy-chain topology and powered via Ethernet cables 
00048 *  with Power-over-EtherCAT (POE) technology. EASE, thus bridges the data 
00049 *  packets between an EtherCAT master and multiple Base boards.
00050 *        
00051 * @code
00052 *#include "mbed.h"
00053 *#include <EsmacatShield.h>      //Include Esmacat Arduino Library
00054 *
00055 *int counter;
00056 *int v[8];                       //EASE 8 registers
00057 *Serial pc(USBTX, USBRX);
00058 *
00059 *DigitalOut selectPin(D10); // D10 is used to drive chip enable low
00060 *SPI spi(D11, D12, D13); // mosi, miso, sclk
00061 *
00062 *
00063 *int main() 
00064 *{
00065 *
00066 *    EsmacatShield slave(spi, selectPin);        //Define Chip Selector Pin
00067 *    
00068 *    slave.setup_spi();      //Setup SPI for EASE, 8 bit Data, Mode 1, 3MHz freq
00069 *    
00070 *    while(1)
00071 *    {
00072 *      slave.get_ecat_registers(v);  //read all registers
00073 *      slave.write_reg_value(0,counter++, true);   //Write register data (register,value, led_on)
00074 *      wait_us(1000000);                      //sleep for 1000 ms
00075 *      slave.write_reg_value(0,counter++, false);   //Write register data (register,value, led_on)
00076 *      wait_us(1000000);                        //sleep for 1000 ms
00077 *      pc.printf("Next Iteration \n");
00078 *      for (int i=0;i<8;i++)     //print the registers read on pc
00079 *      {
00080 *        pc.printf("%d",i);
00081 *        pc.printf("\t");
00082 *        pc.printf("%d",v[i]);
00083 *        pc.printf("\n");
00084 *      }  
00085 *    }
00086 *
00087 *}
00088 * @endcode
00089 */
00090 
00091 
00092 class EsmacatShield
00093 {
00094 public:
00095     /**********************************************************//**
00096     * @brief Constructor for EsmacatShield Class.  
00097     * 
00098     * @details Requires an existing SPI object as well as a DigitalOut object. 
00099     * The DigitalOut object is used for a chip enable signal
00100     *
00101     * On Entry:
00102     *     @param[in] spi - pointer to existing SPI object
00103     *     @param[in] pin - pointer to a DigitalOut pin object
00104     *
00105     * On Exit:
00106     *
00107     * @return None
00108     **************************************************************/
00109   EsmacatShield(SPI &spi, DigitalOut &pin);
00110     /**********************************************************//**
00111     * @brief Set up spi communication.  
00112     * 
00113     * @details Sets up SPI communication by using the member. 
00114     * functions format and frequency. 8 bit data, Mode 1,
00115     * frequency of communication set to 3000000Hz
00116     *
00117     * On Entry:
00118     *     
00119     * On Exit:
00120     *
00121     * @return None
00122     **************************************************************/
00123   void setup_spi();
00124      /**********************************************************//**
00125     * @brief Write given Register with the given value.  
00126     * 
00127     * @details Using this function 8 different 16 bit integers can be 
00128     *          written into EASE.
00129     *
00130     * On Entry:
00131     *     @param[in] write_addr - The Register number to be written into. 
00132     *                Can take values from 0 to 7
00133     *     @param[in] value - The value to be written into the register
00134     *     @param[in] led_on - True to turn LED ON
00135     *                       - False to turn LED OFF
00136     *
00137     * On Exit:
00138     *
00139     * @return None
00140     **************************************************************/ 
00141   void write_reg_value(int write_addr,int16_t value, bool led_on=1);
00142   
00143      /**********************************************************//**
00144     * @brief Read EASE Register.  
00145     * 
00146     * @details Using this function 8 different 16 bit integers on EASE can be
00147     *          read.
00148     *
00149     * On Entry:
00150     *     @param[in] Pointer to integer - Eight consecutive memory locations
00151                      from this pointer will be stored with the integer values read
00152     *                from EASE.
00153     *
00154     * On Exit:
00155     *     @param[out] pointer to the integer where the data is stored.
00156     
00157     *
00158     * @return None
00159     **************************************************************/
00160   int16_t* get_ecat_registers(int16_t regs[8]); 
00161 
00162     /************************************************************
00163     * @brief Default destructor for EsmacatShield Class.  
00164     *
00165     * @details Destroys SPI object if owner 
00166     *
00167     * On Entry:
00168     *
00169     * On Exit:
00170     *
00171     * @return None
00172     **************************************************************/
00173  
00174   ~EsmacatShield();
00175 private:
00176   
00177   SPI &ecat_spi;
00178   DigitalOut &ecat_cs;
00179   int16_t read_reg_value(int16_t read_addr);
00180 };
00181 
00182 
00183 #endif
00184