//  ------------------------------------------------------------------------------
//
//  gI2C_low_level_tx_rx.v -- low level I2C comm for Nintendo Class Mini controller
//
//  Copyright (C) 2020 Michael Gansler
//
//  This program is free software: you can redistribute it and/or modify
//  it under the terms of the GNU General Public License as published by
//  the Free Software Foundation, either version 3 of the License, or
//  (at your option) any later version.
//
//  This program is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU General Public License for more details.
//
//  You should have received a copy of the GNU General Public License
//  along with this program.  If not, see <https://www.gnu.org/licenses/>.
//
//  ------------------------------------------------------------------------------
//
//  Module:       gI2C_low_leveL_tx_rx.v
//
//  Objective:    Performs basic low-level I2C Master operations to 
//                support communications witha Nintendo Class Mini controller.
//
//  Assumptions:  - 40 MHz input clock
//                  Altera MAX10 FPGA
//                - Does not check for ACK's from slave
//                - Does not perform clock stretching
//                - Development done on Terasic DE10-Lite board with 
//                - No clock domain crossings accomodated.  If this module 
//                  were used in an actual situation with clock domain 
//                  crossings or asynchronous inputs, more attention 
//                  (i.e. code changes) would be necessary to manage the 
//                  situation.
//
//  Notes:
//
//  This module performs a number of low-level I2C Master activities.  The
//  intention is that a higher level module coordinates the overall
//  transaction, while this module is commanded by that module 
//  to perform any of the following operations:
//
//    1.  create a start condtion
//    2.  create a stop condtion
//    3.  transmit a byte from master to slave
//    4.  receive a byte from slave to master
//
//  Note that clock stretching is not implemented since this
//  appeared to not be necessary for the the Nintendo Classic Mini 
//  retro controller interfacing application.  Likewise, ACKs/NACKs
//  from the slave are not evaluated.
//
//  The diagram below shows typical  I2C SDA and SCL waverforms:
//
//      START                                                STOP 
//      COND                                                 COND
//      ____       __  __  __  __  __  __  __  __  __         ___
//  SDA     |_____/A6\/A5\/A4\/A3\/A2\/A1\/A0\/RW\/AK\_______|
//
//                  ^   ^   ^   ^   ^   ^   ^   ^   ^
//      ______       _   _   _   _   _   _   _   _   _      _____
//  SCL       |_____| |_| |_| |_| |_| |_| |_| |_| |_| |____|
//
//
// ^'s show SCL rising edge, where receiver samples SDA.
//
// The above shows the case of TX'ing the Address (7 bits) and the
// R/*W bit followed by receiving an ACK from the receiver.  
//
// Data byte transfers in the opposite direction are analogous, 
// 8 bits of data + an ACK/NACK bit.
//
`default_nettype none            // Require all nets to be declared before used.
                                 // --> typo'd net names get trapped

module gI2C_low_level_tx_rx
#(
   parameter TICKS_PER_I2C_CLK_PERIOD = 400   // Ticks of input clock per I2C SCL period (10 usec).
)
(
   //
   // INPUTS
   //
   input wire       clk,         // Input clock, tested with 40 MHz
   
   input wire       rst,         // Reset input
   
   input wire [2:0] command,     // Input command for which I2C operation to create
   
   input wire [7:0] tx_byte,     // Byte to transmit from master to slave (if requested)

   input wire       ACK,         // 1=Master ACKs after slave read, 0=Master NACKs
   
   //
   // OUTPUTS
   //
   output reg [7:0] read_byte,   // Byte read from slave (if requested)
   
   output reg       busy,        // Indicates that this module is busy performing a sequence of actions
   
   output reg       data_valid,  // Indicates that a byte has been read from the slave and is available
   
   output reg       done,        // Indicates that requested action is complete.
   
   //
   // I2C I/O
   //
   input wire       i_sda,       // Input from tristate driver output, connected externally to SDA line   
   
   output reg       o_sda,       // Output from this module indicating how to drive I2C SDA externally
   
   output reg       o_scl        // Output from this module indicating how to drive I2C SCL externally
);

//  ------------------------------------------------------------------------------
//
//  gI2C_mini_nes_read.v -- I2C comm with Nintendo Class Mini controller
//
//  Copyright (C) 2020 Michael Gansler
//
//  This program is free software: you can redistribute it and/or modify
//  it under the terms of the GNU General Public License as published by
//  the Free Software Foundation, either version 3 of the License, or
//  (at your option) any later version.
//
//  This program is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU General Public License for more details.
//
//  You should have received a copy of the GNU General Public License
//  along with this program.  If not, see <https://www.gnu.org/licenses/>.
//
//  ------------------------------------------------------------------------------
//
//  Module:       gI2C_mini_nes_read.v
//
//  Objective:    Performs basic I2C Master operations to communicate with
//                a Nintendo Class Mini controller and read all buttons.
//
//
//  Assumptions:  - 40 MHz input clock
//                - Development done on Terasic DE10-Lite board with 
//                  Altera MAX10 FPGA
//                - No clock domain crossings accomodated.  If this module 
//                  were used in an actual situation with clock domain 
//                  crossings or asynchronous inputs, more attention 
//                  (i.e. code changes) would be necessary to manage the 
//                  situation.
//  Notes:
//
//  This module communicates as a Master over an I2C bus and decodes 
//  button press status from a NES Classi Mini retro controller.  This is 
//  the sort of controller that looks like an original NES controller
//  (up/down/left/right/select/start/A/B), but has a completely different
//  interface than the original.  This updated retro controller has a Wii
//  style connector and an I2C bus.
//
//  The high-level module in this file coordinates the sequences of starts,
//  stops, transmits and reads for a full transaction with the controller.  
//  This obtains the status of all of the buttons: up, down, left, right,
//  select, start, A, and B.  Since this controller is a rendition of the 
//  original NES controller, this is the full set of buttons on the device.
//
//  This module also instantiates a lower level I2c module which handles 
//  the bit by bit signaling of each I2C operation.  The sequence of these
//  operations is coordinated by this upper level module, sending a
//  number of commands to the lower level driver for each operation, 
//  resulting in one full transaction with the device.
//
//  Once transaction consists of the following operations:
//
//   - generate start condition
//   - transmit address to slave, write mode
//   - write 0x00 to slave
//   - generate stop condition
//   - generate start condition
//   - transmit address to slave, read mode
//   - read 6 bytes from slave (the last two bytes contain the button data)
//   - generate a stop condition
//
//  This complete transaction requires less than 1.5 msec, allowing high
//  polling rates of the buttons, if needed.
//
//  The input clock used for testing and development was 40 MHz since this 
//  module was intended for a VGA project that has a 40 MHz pixel clock).  
//
//  Parameterization was done to allow other clock frequencies.  Comments are
//  included describing areas to be mindful of when changing the clock. 
//  The main concern is the counter in the lower-level module (ctr) that 
//  regulates SCL bit timing.  Make sure it has sufficient width if a 
//  faster input clock is used.
//
`default_nettype none                    // Require all nets to be declared before used.
                                         // --> typo'd net names get trapped

module gI2C_mini_nes_read
#( 
   parameter SLAVE_ADDR = 7'h52,         // This is the I2C address of the NES mini controller
   
   parameter TICKS_PER_I2C_CLK = 400     // For 40 MHz clock -> 400.   
                                         // 10 is useful for simulation.
                                         // Note: standard I2C is 100 KHz which means 10 usec/bit.  
                                         // Therefore, if input clk is 40 MHz, then:
                                         // TICKS_PER_I2C_CLK = 40MHz*10usec = 400 counts.
)
(
   //
   // INPUTS 
   //
   input  wire          clk_40,          // Input clock.  Tested with 40 MHz clock
   
   input  wire          rst,             // Active high reset line.
   
   input  wire          request_data,    // Pulse this high to initiate full data transfer sequence
                                         // which includes all Starts, Stops, Master Writes, and Master Reads
                                         // to obtain data from the controller.
   
   //
   // OUTPUTS
   //
   output reg           data_valid,      // Pulse that indicates controller_data was updated with new data.
   
   output reg           busy,            // Module is busy, i.e. transaction in progress

   output reg           btn_none,        // 
   output reg           btn_up,          //
   output reg           btn_down,        //
   output reg           btn_left,        //   Button states decoded from the
   output reg           btn_right,       //   NES mini controller I2C data (bytes 4 and 5).
   output reg           btn_select,      //
   output reg           btn_start,       //
   output reg           btn_B,           //            
   output reg           btn_A,           // 
   
   output reg  [8:0]    buttons,         // Same button state info as above, but as a packed word
   
   //
   // BIDIRECTIONAL
   //
   inout wire           io_sda,          // SDA line to outside world (implements a tristate driver)
   
   inout wire           io_scl           // SCL line to outside world (implements a tristate driver)
);