msp430_bsl 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ca5ed6ae2b592007808e73255f2f1de59c096f5b2e5702ad86fb7dea7c586981
+  data.tar.gz: 6c289eaece5e0fe084ddba9f5847c87da017c51db2825c44d4463a6a10db7e7f
+SHA512:
+  metadata.gz: 327080fb207aabed5bdd0df53f84555268eaf251118c935ee9414547bd437df954b8704cfdd969e0a2cf60e296d9b01a9bf600222fd7a2c96a4f8ca423bf43bd
+  data.tar.gz: 3e8b706fc043fa9048b191e44a5deab69790202418dbbeb51ce93e1ea388637b61847c8cc79129ac6ab1d0a5d0cf4f79f4941263f408e975e9d6341058ea1fec

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Alessandro Verlato
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,56 @@
+# MSP430Bsl
+
+This library is a base for developing MSP430 BSL-based utilities
+   
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'msp430_bsl'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install msp430_bsl
+    
+## Compatibility
+
+Although it's not tested, this library should be compatibile with Ruby 2.7.0 or higher.
+
+## Usage
+
+**Help is appreciated to write some good USAGE**
+
+In the `bin` folder there's the `upload_hex` executable. 
+
+TL;DR: the script can upload a .hex file to the target through a normal UART connection (`rts` and `dtr` pins required). 
+
+**The script has been tested only with CC430F5137**
+
+Just run `bin/upload_hex -h` to show available options.
+
+## TODO
+
+* Write specs
+* Add documentation
+* Write a good Usage
+* Add missing features and generalize the ones already present
+* Delete this TODO section
+
+## Contributing
+
+**Bug reports and pull requests are welcome!**
+
+This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to 
+the [Contributor Covenant](contributor-covenant.org) code of conduct.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+

data/bin/upload_hex

@@ -0,0 +1,86 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+Bundler.require
+require 'slop'
+require_relative '../lib/msp430_bsl'
+
+begin
+  opts = Slop.parse help: true do |o|
+    o.string '-d', '--device', 'Mandatory: Path to serial programmer device', required: true
+    o.string '-f', '--hexfile', 'Mandatory: Path to HEX file to load', required: true
+    o.string '-g', '--logfile', 'Path to logfile'
+    o.string '-l', '--loglevel', "Logger level. One of ['fatal', 'error', 'warn', 'info', 'debug']. Defaults to 'debug'", default: :debug
+    o.bool '-c', '--check', 'Verify flash content after upload', default: true
+    o.bool '-h', '--help', 'Print this help' do
+      puts "#{o}\n"
+      exit
+    end
+  end
+rescue Slop::MissingArgument => e
+  puts "Error: #{e}. Maybe you specified an empty argument?"
+  exit
+rescue Slop::UnknownOption => e
+  puts "Error: #{e}"
+  exit
+end
+
+include Msp430Bsl::Utils
+
+logger = build_logger_from opts
+
+@board = Msp430Bsl::Uart::Connection.new opts[:device], logger: logger
+
+# Enter BSL
+@board.enter_bsl
+# Mass erase FLASH
+logger.info 'Mass erasing FLASH'
+@board.send_command :mass_erase
+# Unlock BSL protected commands
+logger.info "'Unlocking BSL's password protected commands'"
+@board.send_command :rx_password, data: Msp430Bsl::Configs::CMD_RX_PASSWORD
+# Switch UART to max speed
+logger.info 'Changing UART BAUD to 115200'
+@board.send_command :change_baud_rate, data: Msp430Bsl::Configs::BAUD_RATES[115200]
+@board.set_uart_speed 115200
+
+# If everything has gone well so far...
+hexfile = Msp430Bsl::HexFile.new opts[:hexfile]
+
+# Group lines by contiguous memory addr
+logger.info 'Writing data into FLASH'
+line_groups = hexfile.data_lines_grouped_by_contiguous_addr
+# Try to optimize BSL writes
+# For each lines group, append as many lines as possible, given the BSL Core Commands buffer size
+line_groups.each do |group|
+  curr_data_packet = []
+  curr_data_size = 0
+  # Cycle lines in a group
+  group.each do |line|
+    if curr_data_packet.empty?
+      # Use current line's addr as packet addr
+      curr_data_packet << line
+      curr_data_size += 2 + line.data_length  # 2 is the addr size (2 bytes)
+    elsif (curr_data_size + line.data_length) <= Msp430Bsl::Uart::Connection::CORE_COMMANDS_BUFFER_SIZE
+      # If there's still room, append the line data
+      curr_data_packet << line
+      curr_data_size += line.data_length
+    else
+      # No room left, send packet
+      @board.send_command :rx_data_block, addr: curr_data_packet.first.addr, data: curr_data_packet.map { |line| line.data }.reduce(:+)
+      curr_data_packet = []
+      curr_data_size = 0
+      redo  # Handle current line than would otherwise be skipped
+    end
+  end
+
+  # Send residual lines before handling next group
+  if curr_data_packet.any?
+    @board.send_command :rx_data_block, addr: curr_data_packet.first.addr, data: curr_data_packet.map { |line| line.data }.reduce(:+)
+  end
+end
+
+# TODO: Verify CRC or read entire flash and compare to hex lines?
+
+logger.info 'Closing connection'
+@board.close_connection

data/lib/core_ext/array.rb

@@ -0,0 +1,13 @@
+class Array
+  def to_hex
+    map { |el| el.to_hex_str }
+  end
+
+  def to_chr
+    map { |el| el.chr }
+  end
+
+  def to_chr_string
+    to_chr.join
+  end
+end

data/lib/core_ext/number.rb

@@ -0,0 +1,19 @@
+class Numeric
+  def to_hex_str
+    n = to_s(16).upcase
+    if n.length.odd?
+      n = "0#{n}"
+    end
+    n
+  end
+
+  def to_bytes_ary
+    res = []
+    to_hex_str.chars.each_slice(2) { |byte| res << byte.join().to_i(16) }
+    res
+  end
+
+  def millis
+    self / 1_000.0
+  end
+end

data/lib/core_ext/string.rb

@@ -0,0 +1,8 @@
+class String
+
+  def to_hex_ary
+    res = []
+    chars.each_slice(2) { |byte| res << byte.join().to_i(16) }
+    res
+  end
+end

data/lib/msp430_bsl/command.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Msp430Bsl
+  class Command
+
+    attr_accessor :name, :code, :addr, :data, :configs
+
+    def self.supports?(cmd_name)
+      Configs::CMDS.keys.include? cmd_name.to_sym
+    end
+
+    def self.[](cmd_name)
+      raise Exceptions::Command::NameNotSupported, cmd_name unless supports?(cmd_name)
+
+      Configs::CMDS[cmd_name.to_sym]
+    end
+
+    def initialize(cmd_name, addr: nil, data: nil)
+      raise Exceptions::Command::NameNotSupported, cmd_name unless self.class.supports?(cmd_name)
+
+      @name = cmd_name
+      @configs = self.class[@name]
+      @code = configs[:code]
+      @addr = addr
+      @data = data
+
+      validate
+    end
+
+    def packet
+      return @packet if @packet
+
+      @packet = [code, splitted_addr, data].flatten.compact
+    end
+
+    def length
+      code.to_bytes_ary.length
+    end
+
+    # Split address to [low, middle, high] bytes
+    def splitted_addr
+      if addr
+        [ (addr & 0xFF), ((addr >> 8) & 0xFF), ((addr >> 16) & 0xFF) ]
+      end
+    end
+
+    private
+
+    def validate
+      # Check if command requires address and/or data
+      if configs[:requires_addr] && !addr
+        raise Exceptions::Command::RequiresAddr.new name
+      end
+
+      if configs[:requires_data] && !data
+        raise Exceptions::Command::RequiresData.new name
+      end
+    end
+  end
+end

data/lib/msp430_bsl/configs.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Msp430Bsl
+  module Configs
+    CMD_KINDS = {
+      data: { code: 0x3A, payload_min_size: 2 },
+      message: { code: 0x3B, payload_size: 1 }
+    }.freeze
+
+    CMDS = {
+      rx_data_block:      { code: 0x10, requires_addr: true, requires_data: true,     response: { kind: CMD_KINDS[:message][:code], data_size: 1 }},
+      rx_data_block_fast: { code: 0x1B, requires_addr: true, requires_data: true,     response: { kind: nil, data_size: 1 }},
+      rx_password:        { code: 0x11, requires_addr: false, requires_data: true,    response: { kind: CMD_KINDS[:message][:code], data_size: 1 }},
+      erase_segment:      { code: 0x12, requires_addr: true, requires_data: false,    response: { kind: CMD_KINDS[:message][:code], data_size: 1 }},
+      lock_unlock_info:   { code: 0x13, requires_addr: false , requires_data: false,  response: { kind: CMD_KINDS[:message][:code], data_size: 1 }},
+      reserved:           { code: 0x14, requires_addr: false , requires_data: false,  response: { kind: CMD_KINDS[:message][:code], data_size: 1 }},
+      mass_erase:         { code: 0x15, requires_addr: false , requires_data: false,  response: { kind: CMD_KINDS[:message][:code], data_size: 1 }},
+      crc_check:          { code: 0x16, requires_addr: true , requires_data: true,    response: { kind: CMD_KINDS[:data][:code], data_size: 2 }},
+      load_pc:            { code: 0x17, requires_addr: true, requires_data: false,    response: { kind: CMD_KINDS[:message][:code], data_size: 1 }},
+      tx_data_block:      { code: 0x18, requires_addr: true, requires_data: true,     response: { kind: CMD_KINDS[:data][:code], data_size_min: 1 }},
+      tx_bsl_version:     { code: 0x19, requires_addr: false , requires_data: false,  response: { kind: CMD_KINDS[:data][:code], data_size: 4 }},
+      tx_buffer_size:     { code: 0x1A, requires_addr: false , requires_data: false,  response: { kind: CMD_KINDS[:data][:code], data_size: 2 }},
+      change_baud_rate:   { code: 0x52, requires_addr: false , requires_data: true,   response: { kind: nil }}
+    }
+
+    RESPONSE_MESSAGES = {
+      success:                  { code: 0x00, reason: 'Operation Successful' },
+      flash_write_check_failed: { code: 0x01, reason: 'Flash Write Check Failed. After programming, a CRC is run on the programmed data. If the CRC does not match the expected result, this error is returned' },
+      flash_fail_bit_set:       { code: 0x02, reason: "Flash Fail Bit Set. An operation set the FAIL bit in the flash controller (see the MSP430F5xx and MSP430F6xx Family User's Guide for more details on the flash fail bit)" },
+      voltage_changed:          { code: 0x03, reason: "Voltage Change During Program. The VPE was set during the requested write operation (see the MSP430F5xx and MSP430F6xx Family User's Guide for more details on the VPE bit)" },
+      bsl_locked:               { code: 0x04, reason: 'BSL Locked. The correct password has not yet been supplied to unlock the BSL' },
+      bsl_password_error:       { code: 0x05, reason: 'BSL Password Error. An incorrect password was supplied to the BSL when attempting an unlock' },
+      byte_write_forbidden:     { code: 0x06, reason: 'Byte Write Forbidden. This error is returned when a byte write is attempted in a flash area' },
+      unknown_command:          { code: 0x07, reason: 'Unknown Command. The command given to the BSL was not recognized.' },
+      packet_too_large:         { code: 0x08, reason: 'Packet Length Exceeds Buffer Size. The supplied packet length value is too large to be held in the BSL receive buffer' }
+    }
+
+    CMD_RX_PASSWORD = Array.new(32) { 0xFF }
+
+    BAUD_RATES = {
+      9600 => 0x02,
+      19200 => 0x03,
+      38400 => 0x04,
+      57600 => 0x05,
+      115200 => 0x06
+    }.freeze
+  end
+end

data/lib/msp430_bsl/exceptions.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Msp430Bsl
+  module Exceptions
+    module Command
+      class NameNotSupported < StandardError
+        def initialize(given_name)
+          message = "command '#{given_name}' not recognized. Supported commands: #{Configs::CMDS.keys}"
+          super(message)
+        end
+      end
+
+      class RequiresAddr < StandardError
+        def initialize(cmd_name)
+          msg = "command '#{cmd_name}' requires 'addr' param"
+          super(msg)
+        end
+      end
+
+      class RequiresData < StandardError
+        def initialize(cmd_name)
+          msg = "command '#{cmd_name}' requires 'data' param"
+          super(msg)
+        end
+      end
+    end
+
+    module Response
+      class KindNotSupported < StandardError
+        def initialize(kind)
+          message = "Response kind '0x#{kind.to_hex_str}' not recognized. Supported response kinds: #{Configs::CMD_KINDS.keys}"
+          super(message)
+        end
+      end
+
+      class NotValid < StandardError
+        def initialize(errors)
+          message = "Response not valid. Errors: \n\n#{errors.map { |err| " - #{err[1]}" }.join "\n" }\n"
+          super(message)
+        end
+      end
+
+      class WrongDataSize < StandardError
+        def initialize(data, size, min: false)
+          message = "payload with a size of '#{data.size}' doesn't satisfy the required #{min ? 'min' : ''}size of '#{size}'"
+          super(message)
+        end
+      end
+    end
+  end
+end

data/lib/msp430_bsl/hex_file.rb

@@ -0,0 +1,51 @@
+module Msp430Bsl
+  class HexFile
+
+    attr_reader :path, :raw_data
+
+    def initialize(path)
+      @path = File.expand_path path
+      @raw_data = File.read path
+    end
+
+    def lines
+      return @lines if @lines
+
+      @lines = []
+      raw_data.each_line.with_index { |line, i| @lines << HexLine.new(line, num: i) }
+      @lines
+    end
+
+    def data_lines_grouped_by_contiguous_addr
+      return @grouped_lines if @grouped_lines
+
+      @grouped_lines = []
+      curr_group = nil
+      curr_addr = nil
+      prev_line = nil
+      lines.each do |line|
+        next unless line.is_of_type? :data
+
+        if curr_addr.nil?
+          # We just started a new group
+          curr_addr = line.addr
+          curr_group = [line]
+        elsif line.has_addr_contiguous_to? prev_line
+          # We already have a current group
+          curr_group << line
+          curr_addr = line.addr
+        else
+          @grouped_lines << curr_group
+          curr_addr = nil
+          redo
+        end
+
+        prev_line = line
+      end
+
+      @grouped_lines << curr_group if curr_group.any?
+
+      @grouped_lines
+    end
+  end
+end

data/lib/msp430_bsl/hex_line.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Msp430Bsl
+  class HexLine
+    include Utils
+
+    attr_reader :raw_data, :data_length, :addr, :type, :data, :crc, :number
+
+    RECORD_TYPES = {
+      data: 0x00,
+      eof: 0x01,
+      ext_seg_addr: 0x02,
+      start_seg_addr: 0x03,
+      ext_lin_addr: 0x04,
+      start_lin_addr: 0x05
+    }.freeze
+
+    def initialize(data, num: nil)
+      raise StandardError, 'raw_data must be a String' unless data.is_a?(String)
+
+      # Strip String, remove first char i.e. ':' and convert char couples to its hex value.
+      @raw_data = data.strip[1..-1].to_hex_ary
+
+      @data_length = raw_data[0]
+      @addr = (raw_data[1] << 8) | raw_data[2]
+      @type = raw_data[3]
+      @data = raw_data.slice 4, data_length
+      @crc = raw_data[-1]
+      @number = num
+    end
+
+    # Checks if this line's address is contiguous with the one of the given line
+    # Obviously this can be true only if the given line has an address that precedes this line's one
+    def has_addr_contiguous_to?(another_line)
+      another_line.addr + another_line.data_length == addr
+    end
+
+    def crc_ok?
+      crc == crc8(raw_data[0..-2])
+    end
+
+    def is_of_type?(ty)
+      ty = ty.to_sym
+      type == RECORD_TYPES[ty]
+    end
+  end
+end

data/lib/msp430_bsl/response.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Msp430Bsl
+  class Response
+
+    class << self
+      def supports_kind?(kind)
+        Configs::CMD_KINDS.values.map { |val| val[:code] }.include? kind
+      end
+    end
+
+    attr_reader :kind, :data, :errors
+
+    def initialize(payload)
+      raise ArgumentError, 'payload must be an Array' unless payload.is_a?(Array)
+
+      @kind = payload[0]
+      raise Exceptions::Response::KindNotSupported, kind unless self.class.supports_kind?(kind)
+
+      @data = payload[1..-1]
+
+      if is_data?
+        raise Exceptions::Response::WrongDataSize.new(data, Configs::CMD_KINDS[:data][:payload_min_size]) if data.size < Configs::CMD_KINDS[:data][:payload_min_size]
+      else
+        raise Exceptions::Response::WrongDataSize.new(data, Configs::CMD_KINDS[:message][:payload_size]) if data.size != Configs::CMD_KINDS[:message][:payload_size]
+      end
+    end
+
+    def is_data?
+      kind == Configs::CMD_KINDS[:data]
+    end
+
+    def is_message?
+      kind == Configs::CMD_KINDS[:message][:code]
+    end
+
+    def is_ok_given_command?(command)
+      @errors = []
+
+      # Verify if response kind is compatible with sent command
+      unless kind == command.configs[:response][:kind]
+        @errors << [:kind, "Kind NOK. Expected response kind: 0x#{command.configs[:response][:kind].to_hex_str} - got: 0x#{kind.to_hex_str}"]
+      end
+      # Check response exact data size
+      if command.configs.has_key?(:data_size) && data.size != command.configs[:data_size]
+        @errors << [:data_size, "Data size NOK. Expected data size to be exactly '#{command.configs[:data_size]}' bytes, got '#{data.size}' bytes"]
+      end
+      # Check response min data size
+      if command.configs.has_key?(:data_size_min) && data.size < command.configs[:data_size_min]
+        @errors << [:data_size_min, "Min data size NOK. Expected data to have at least a size of '#{command.configs[:min_data_size]}' bytes, got '#{data.size}' bytes"]
+      end
+      # If kind is "message" check response code
+      if is_message?
+        success_code = Configs::RESPONSE_MESSAGES[:success][:code]
+        if data[0] != success_code  # First (and only) data byte is message code
+          @errors << [:message_code, "Message code NOK. Expected message code '#{success_code}', got '#{data[0]}'"]
+        end
+      end
+
+      @errors.empty?
+    end
+  end
+end

data/lib/msp430_bsl/uart/ack.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Msp430Bsl
+  module Uart
+    class Ack
+
+      MESSAGES = {
+        0x00 => { code: :ack, reason: 'ACK - Command correctly received' },
+        0x51 => { code: :header_nok, reason: 'Header incorrect. The packet did not begin with the required 0x80 value' },
+        0x52 => { code: :crc_nok, reason: 'Checksum incorrect. The packet did not have the correct checksum value' },
+        0x53 => { code: :packet_size_zero, reason: 'Packet size zero. The size for the BSL core command was given as 0' },
+        0x54 => { code: :packet_size_exceeds, reason: 'Packet size exceeds buffer. The packet size given is too big for the RX buffer' },
+        0x55 => { code: :unkown_error, reason: 'Unknown error' },
+        0x56 => { code: :unkown_baudrate, reason: 'Unknown baud rate. The supplied data for baud rate change is not a known value' }
+      }
+
+      attr_accessor :value, :message
+
+      def initialize(value)
+        raise Exceptions::Ack::MessageNotSupported, value unless MESSAGES.include?(value)
+
+        @value = value
+        @message = MESSAGES[@value]
+      end
+
+      def ok?
+        value == 0x00
+      end
+
+      def reason
+        message[:reason]
+      end
+    end
+  end
+end

data/lib/msp430_bsl/uart/connection.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+require 'logger'
+require 'timeout'
+
+module Msp430Bsl
+  module Uart
+    class Connection
+
+      UART_CONFIGS = { data_bits: 8, stop_bits: 1, parity: SerialPort::EVEN }.transform_keys(&:to_s).freeze
+
+      WAIT_FOR_ACK_MAX      = 100.millis
+      WAIT_FOR_RESPONSE_MAX = 100.millis
+
+      MEM_START_MAIN_FLASH      = 0x8000
+
+      CORE_COMMANDS_BUFFER_SIZE     = 260
+
+      attr_reader :serial_port, :device_path, :logger, :cmd_buff_size
+
+      def initialize(device_path, opts = {})
+        @device_path = device_path
+        @logger = opts.fetch :logger, Logger.new(STDOUT)
+        @cmd_buff_size = opts.fetch :cmd_buf_size, CORE_COMMANDS_BUFFER_SIZE
+
+        @serial_port = SerialPort.new @device_path
+      end
+
+      def close_connection
+        serial_port.close
+      end
+
+      def check_bsl_reply
+        reply.length > 1 && reply[0] == BSL_MESSAGE && reply[1] == BSL_OK
+      end
+
+      def enter_bsl
+        logger.info "Connecting to target board through UART on #{device_path}"
+        set_uart_speed 9600
+        invoke_bsl
+      end
+
+      def read_response_for(command)
+        raise ArgumentError, "an instance of Msp430Bsl::Command is expected as argument. Given: '#{command.class}'" unless command.is_a?(Command)
+
+        # Wait for first response byte - UART's ACK/NACK
+        ack = nil
+        begin
+          Timeout::timeout(WAIT_FOR_ACK_MAX) do
+            ack = Ack.new serial_port.getbyte
+          end
+        rescue Timeout::Error => e
+          logger.error 'Timeout occurred while waiting for UART ACK'
+          raise e
+        end
+
+        # If we arrived here, ack has been populated
+        if ack && ack.ok?
+          logger.debug "IN  <- ACK (1 byte) 0x#{ack.value.to_hex_str}"
+        else
+          logger.error ack.reason
+          raise Exceptions::Ack::NOK, ack.value
+        end
+
+        # If this command has not response, return
+        unless command.configs[:response][:kind]
+          return ack
+        end
+
+        # Wait for command response
+        begin
+          pi = PeripheralInterface.new
+          Timeout::timeout(WAIT_FOR_RESPONSE_MAX) do
+            loop do
+              read = serial_port.readpartial cmd_buff_size
+              pi.push read.unpack 'C*'
+              break if pi.valid?
+            end
+          end
+        rescue Timeout::Error => e
+          logger.error 'Timeout occurred while fetching response from UART'
+          raise e
+        end
+
+        # Unwrap PeripheralInterface and create Response
+        logger.debug "IN  <- RES (#{pi.packet.size} bytes) #{pi.to_hex_ary_str}"
+        response = pi.to_response
+        unless response.is_ok_given_command? command
+          raise Msp430Bsl::Exceptions::Response::NotValid, response.errors
+        end
+
+        response
+      end
+
+      def send_command(cmd_name, addr: nil, data: nil, log_only: false)
+        command = Command.new cmd_name, addr: addr, data: data
+        pi = PeripheralInterface.wrap command
+        logger.debug "Sending command '#{command.name}' over UART"
+        # Flush serial's output and input before sending a new command
+        serial_port.flush_output
+        serial_port.flush_input
+
+        unless pi.valid?
+          logger.error "PeripheralInterface not valid. Errors: #{pi.errors}"
+          return nil
+        end
+
+        logger.debug "OUT -> (#{pi.packet.size} bytes) #{pi.to_hex_ary_str}"
+        unless log_only
+          serial_port.write pi.to_uart
+          read_response_for command
+        end
+      end
+
+      def set_uart_speed(baud)
+        raise StandardError, "BAUD not supported. Supported BAUD: #{Configs::BAUD_RATES.keys}" unless Configs::BAUD_RATES.keys.include?(baud)
+
+        logger.debug "Setting serial port BAUD to #{baud} bps"
+
+        serial_port.set_modem_params UART_CONFIGS.merge('baud' => baud)  # We must use strings as keys
+        test_pin_go :high
+        reset_pin_go :low
+      end
+
+      def trigger_reset
+        # slau319 pag. 5 - Fig. 1-1
+        reset_pin_go :low
+        test_pin_go :low
+        sleep 5.millis
+        reset_pin_go :high
+      end
+
+      private
+
+      def convert_pin(value, negate: false)
+        res = case value
+              when Symbol
+                value == :high ? 1 : 0
+              when Numeric
+                value == 1 ? 1 : 0
+              when TrueClass
+                1
+              when FalseClass
+                0
+              else
+                raise ArgumentError, 'convert_pin: value not supported'
+              end
+
+        if negate
+          res = res == 1 ? 0 : 1
+        end
+
+        res
+      end
+
+      def invoke_bsl
+        serial_port.flush_input
+        serial_port.flush_output
+
+        logger.info 'Entering BSL...'
+
+        test_pin_go(:low)
+        reset_pin_go(:low)
+        sleep 5.millis
+        2.times do
+          test_pin_go(:high)
+          sleep 1.millis
+          test_pin_go(:low)
+          sleep 1.millis
+        end
+
+        test_pin_go(:high)
+        sleep 1.millis
+        reset_pin_go(:high)
+        sleep 1.millis
+        test_pin_go :low
+        sleep 50.millis # Give microcontroller time to enter BSL
+
+        logger.info 'OK, BSL ready'
+      end
+
+      def negate_pin(value)
+        raise ArgumentError, "value must be Numeric (0,1)" unless value.is_a?(Numeric)
+
+        value == 1 ? 0 : 1
+      end
+
+      def reset_pin_go(value)
+        serial_port.dtr = convert_pin value, negate: true
+      end
+
+      def test_pin_go(value)
+        serial_port.rts = convert_pin value, negate: true
+      end
+    end
+  end
+end

data/lib/msp430_bsl/uart/exceptions.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Msp430Bsl
+  module Uart
+    module Exceptions
+      module Ack
+
+        class NOK <  StandardError
+          def initialize(val)
+            message = "Command ACK not OK. Received value: #{val}"
+            super(message)
+          end
+        end
+        class MessageNotSupported < StandardError
+          def initialize(value)
+            message = "message with value 0x#{value.to_hex_str} not supported"
+            super(message)
+          end
+        end
+      end
+
+      module PeripheralInterface
+        class InterfaceWrapNotACommand < StandardError
+          def initialize(arg)
+            message = "Given argument '#{arg}' must be a Msp430Bsl::Command"
+            super(message)
+          end
+        end
+
+        class InterfaceParseRawDataNotArray < StandardError
+          def initialize
+            message = "PeripheralInterface#parse argument must be an Array"
+            super(message)
+          end
+        end
+
+        class InterfaceDataNotArray < StandardError
+          def initialize
+            message = "Peripheral Interface 'data' argument must be an Array"
+            super(message)
+          end
+        end
+
+        class InterfaceSize < StandardError
+          def initialize(received_size)
+            message = "Peripheral Interface size error. Required packet's min size is '#{PeripheralInterface::MIN_PACKET_SIZE}' bytes, given raw_data size is '#{received_size}' bytes"
+            super(message)
+          end
+        end
+
+        class InterfaceHeaderNOK < StandardError
+          def initialize(received_header)
+            message = "Peripheral interface header NOK. Received '0x#{received_header.to_hex_str}' instead of 0x#{PeripheralInterface::OK_HEADER.to_hex_str}"
+            super(message)
+          end
+
+        end
+
+        class InterfaceCRCMismatch < StandardError
+          def initialize
+            message = 'Peripheral Interface CRC mismatch'
+            super(message)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/msp430_bsl/uart/peripheral_interface.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Msp430Bsl
+  module Uart
+    class PeripheralInterface
+      include Utils
+
+      MIN_PACKET_SIZE = 6.freeze     # bytes
+      OK_HEADER       = 0x80.freeze
+
+      HEADER_SIZE   = 1.freeze
+      DATA_LEN_SIZE = 2.freeze
+      CRC_SIZE      = 2.freeze
+
+      class << self
+        include Utils
+
+        def wrap(command)
+          unless command.is_a?(Command)
+            raise Exceptions::PeripheralInterfaceWrapNotACommand, command
+          end
+
+          new header: OK_HEADER, data_len: command.packet.size, data: command.packet
+        end
+
+        def parse(raw_data)
+          raise Exceptions::PeripheralInterfaceParseRawDataNotArray unless raw_data.is_a?(Array)
+          raise Exceptions::PeripheralInterfaceSize, raw_data.size unless raw_data.size >= MIN_PACKET_SIZE
+
+          header = raw_data[0]
+          data_len = raw_data[2] << 8 | raw_data[1]
+          data = raw_data[3, data_len]
+          crc = raw_data[-1] << 8 | raw_data[-2]
+
+          new header: header, data_len: data_len, data: data, crc: crc
+        end
+      end
+
+      attr_reader :header, :data_len, :data, :crc, :errors, :packet, :cmd_kind
+
+      def initialize(header: nil, data_len: nil, data: nil, crc: nil)
+        raise Exceptions::PeripheralInterfaceDataNotArray if (data && !data.is_a?(Array))
+
+        @header = header
+        @data_len = data_len
+        @data = data
+        @crc = crc ? crc : (data ? crc16(data) : nil)
+        @cmd_code
+
+        @partial_data = []
+      end
+
+      def crc_ok?
+        data && crc == crc16(data)
+      end
+
+      def header_ok?
+        header == OK_HEADER
+      end
+
+      def data_len_ok?
+        data&.length == data_len
+      end
+
+      def length
+        packet.length
+      end
+
+      def packet
+        res = data.clone
+        cmd_len = res.length
+        # Calculate CRC (it must be calculated only on command data)
+        crc = crc16 res
+        # Prepend preamble
+        res.prepend 0x80, (cmd_len & 0xFF), ((cmd_len >> 8) & 0xFF)
+        # Append CRC16
+        res.append (crc & 0xFF), ((crc >> 8) & 0xFF)
+      end
+
+      def push(val)
+        @partial_data.append *val
+
+        # If :header has not already been fetched
+        if !header && @partial_data.size >= HEADER_SIZE
+          @header = @partial_data.shift
+        end
+        # If :data_len has not already been fetched, and we have enough data
+        if header && !data_len && @partial_data.size >= DATA_LEN_SIZE
+          values = @partial_data.shift DATA_LEN_SIZE
+          @data_len = values[0] | (values[1] << 8)
+        end
+
+        # If :data has not already been fetched, fetch it
+        if data_len && (data.nil? || data.empty?) && @partial_data.size >= data_len
+          @data = @partial_data.shift data_len
+        end
+
+        if data && !crc && @partial_data.size >= CRC_SIZE
+          values = @partial_data.shift CRC_SIZE
+          @crc = values[0] | (values[1] << 8)
+        end
+      end
+      alias_method :<<, :push
+
+      def to_hex_ary_str
+        packet.to_hex
+      end
+
+      def to_uart
+        packet.to_chr_string
+      end
+
+      def to_response
+        Response.new data
+      end
+
+      def valid?
+        @errors = []
+        @errors << [:header, 'Header NOK'] unless header_ok?
+        @errors << [:data_len, "'data_len' value (#{data_len}) differs from current data length (#{data&.length})"] unless data_len_ok?
+        @errors << [:crc, 'CRC NOK'] unless crc_ok?
+
+        @errors.empty?
+      end
+
+      private
+
+      def parse_raw_data
+        @header = raw_data[0]
+        @data_len = raw_data[2] << 8 | raw_data[1]
+        @data = raw_data[3, data_len]
+        @crc = raw_data[-1] << 8 | raw_data[-2]
+      end
+    end
+  end
+end

data/lib/msp430_bsl/utils.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+require 'logger'
+
+module Msp430Bsl
+  module Utils
+    def crc16(data)
+      raise ArgumentError, 'data must be an Array' unless data.is_a?(Array)
+
+      crc = 0xFFFF
+
+      data.each do |byte|
+        x = (crc >> 8 ^ byte) & 0xFF
+        x ^= x >> 4
+        crc = (crc << 8) ^ (x << 12) ^ (x << 5) ^ x
+      end
+
+      crc & 0xFFFF
+    end
+
+    def crc8(data)
+      (~data.reduce(:+) + 1) & 0xFF
+    end
+
+    def build_logger_from(opts)
+      logto = if opts[:logfile]
+                File.expand_path opts[:logfile]
+              else
+                STDOUT
+              end
+
+      Logger.new logto, level: normalize_log_level(opts[:loglevel])
+    end
+
+    def normalize_log_level(level)
+      case level
+      when :debug, ::Logger::DEBUG, 'debug', 'd' then ::Logger::DEBUG
+      when :info,  ::Logger::INFO,  'info', 'i'  then ::Logger::INFO
+      when :warn,  ::Logger::WARN,  'warn', 'w'  then ::Logger::WARN
+      when :error, ::Logger::ERROR, 'error', 'e' then ::Logger::ERROR
+      when :fatal, ::Logger::FATAL, 'fatal', 'f' then ::Logger::FATAL
+      else
+        ENV['LOG_LEVEL'] || Logger::DEBUG
+      end
+    end
+  end
+end

data/lib/msp430_bsl/version.rb

@@ -0,0 +1,3 @@
+module Msp430Bsl
+  VERSION = '0.0.1'.freeze
+end

data/lib/msp430_bsl.rb

@@ -0,0 +1,14 @@
+require 'zeitwerk'
+require 'serialport'
+
+loader = Zeitwerk::Loader.new
+loader.push_dir File.expand_path(__dir__)
+core_ext = File.expand_path('core_ext', __dir__)
+loader.ignore core_ext
+loader.setup
+
+# Require core_ext files
+Dir["#{core_ext}/**/*.rb"].each { |file| require file }
+
+module Msp430Bsl
+end

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: msp430_bsl
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Alessandro Verlato
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-06-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.6.8
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.6.8
+- !ruby/object:Gem::Dependency
+  name: serialport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.3.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.3.2
+- !ruby/object:Gem::Dependency
+  name: slop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 4.10.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 4.10.1
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.14.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.14.2
+description:
+email:
+- averlato@gmail.com
+executables:
+- upload_hex
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- bin/upload_hex
+- lib/core_ext/array.rb
+- lib/core_ext/number.rb
+- lib/core_ext/string.rb
+- lib/msp430_bsl.rb
+- lib/msp430_bsl/command.rb
+- lib/msp430_bsl/configs.rb
+- lib/msp430_bsl/exceptions.rb
+- lib/msp430_bsl/hex_file.rb
+- lib/msp430_bsl/hex_line.rb
+- lib/msp430_bsl/response.rb
+- lib/msp430_bsl/uart/ack.rb
+- lib/msp430_bsl/uart/connection.rb
+- lib/msp430_bsl/uart/exceptions.rb
+- lib/msp430_bsl/uart/peripheral_interface.rb
+- lib/msp430_bsl/utils.rb
+- lib/msp430_bsl/version.rb
+homepage: https://github.com/madAle/msp430_bsl
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.6
+signing_key:
+specification_version: 4
+summary: Texas Instrument MSP430 BSL Ruby library
+test_files: []