note
	description: "[
		8-bit binary op code instructions and instruction builder functions for
		HD44780 VFD/LCD controllers.
		
		All instructions are 8-bit aligned so if you are using a 4-bit serial communication
		channel then you will need to transmit the low and high 4-bits one after another.
	]"
	legal   : "See notice at end of class."
	status  : "See notice at end of class.";
	author  : "Paul Bates (paul.a.bates@gmail.com)"
	date    : "$Date$"
	revision: "$Revision$"

frozen class
	HD44780_OP_CODES

feature -- Initialization

	function_set_op (a_data_length: NATURAL_8; a_lines: NATURAL_8; a_font: NATURAL_8): NATURAL_8
			-- Returns binary encoded instruction for setting display function parameters
			-- Processing Time: ~40uS
			--
			-- `a_data_length' Data pipe transmission length.
			-- `a_lines': Number of lines (rows) on the display.
			-- `a_font': Display font Width x Height.
		require
			a_data_length_valid:
				a_data_length = function_data_length_4bit or
				a_data_length = function_data_length_8bit
			a_lines_valid:
				a_lines = function_lines_single or
				a_lines = function_lines_multi
			a_font_valid:
				a_font = function_font_5x7 or
				a_font = function_font_5x10
		do
			Result := function_set_ins | a_data_length | a_lines | a_font
		ensure
			instruction_set: (Result & function_set_ins) = function_set_ins
			data_length_set: (Result & a_data_length) = a_data_length
			lines_set: (Result & a_lines) = a_lines
			font_set: (Result & a_font) = a_font
		end

	cursor_display_shift_op (a_shift_mode: NATURAL_8; a_shift_direction: NATURAL_8): NATURAL_8
			-- Returns binary encoded instruction for cursor shift behavior when character data is send to display.
			-- Processing time: ~40uS
			--
			-- `a_shift_mode': The shifting mode; display or cursor.
			-- `a_shift_direction' The direction to shift the display; left of right.
		require
			a_shift_mode_valid:
				a_shift_mode = cursor_display_shift_display or
				a_shift_mode = cursor_display_shift_cursor
			a_shift_direction_valid:
				a_shift_direction = cursor_display_shift_right or
				a_shift_direction = cursor_display_shift_left
		do
			Result := cursor_display_shift_ins | a_shift_mode | a_shift_direction
		ensure
			instruction_set: (Result & cursor_display_shift_ins) = cursor_display_shift_ins
			shift_mode_set: (Result & a_shift_mode) = a_shift_mode
			shift_direction_set: (Result & a_shift_direction) = a_shift_direction
		end

	entry_mode_op (a_shift_mode: NATURAL_8; a_character_shift_mode: NATURAL_8): NATURAL_8
			-- Returns binary encoded instruction for setting entry mode controlling cursor behavior when character data is send
			-- to display (~40uS)
			-- `a_shift_mode': Shift display or character.
			-- `a_character_shift_mode': Increment or decrement cursor position.
		require
			a_shift_valid:
				a_shift_mode = entry_shift_none or
				a_shift_mode = entry_shift_display
			a_character_shift_mode_valid:
				a_character_shift_mode = entry_move_increment_cursor or
				a_character_shift_mode = entry_move_decrement_cursor
		do
			Result := entry_mode_ins | a_shift_mode | a_character_shift_mode
		ensure
			instruction_set: (Result & entry_mode_ins) = entry_mode_ins
			shift_mode_set: (Result & a_shift_mode) = a_shift_mode
			character_shift_mode_set: (Result & a_character_shift_mode) = a_character_shift_mode
		end

	display_control_op (a_display_mode: NATURAL_8; a_cursor_mode: NATURAL_8; a_blink_cursor_mode: NATURAL_8): NATURAL_8
			-- Returns binary encoded instruction for setting a display mode.
			-- Processing time: ~40uS
			--
			-- `a_display_mode': Display mode (on or off).
			-- `a_cursor_mode': Underscore cursor diplay mode (on or off).
			-- `a_blink_cursor_mode': Blinking cursor diplay mode (on or off).
		require
			a_display_mode_valid:
				a_display_mode = display_on or
				a_display_mode = display_off
			a_cursor_mode_valid:
				a_cursor_mode = display_cursor_on or
				a_cursor_mode = display_cursor_off
			a_blink_cursor_mode_valid:
				a_blink_cursor_mode = display_blink_cursor_on or
				a_blink_cursor_mode = display_blink_cursor_off
		do
			Result := display_control_ins.bit_or (a_display_mode).bit_or (a_cursor_mode).bit_or (a_blink_cursor_mode)
		ensure
			instruction_set: (Result & display_control_ins) = display_control_ins
			display_mode_set: (Result & a_display_mode) = a_display_mode
			cursor_mode_set: (Result & a_cursor_mode) = a_cursor_mode
			blink_cursor_mode_set: (Result & a_blink_cursor_mode) = a_blink_cursor_mode
		end

feature -- Basic operations

	clear_display_op: NATURAL_8 = 0b00000001
			-- Clears display and returns cursor to home position
			-- Processing time: ~1.68mS

feature -- Cursor operations

	send_cursor_home_op: NATURAL_8 = 0b00000010
			-- Returns cursor to home position
			-- Also returns display being shifted from original position.
			-- DDRAM contents will remain unchanged.
			-- Processing time: ~1.68mS

feature -- Commands

	set_cgram_address_op (a_address: NATURAL_8): NATURAL_8
			-- Returns binary encoded instruction for setting a Character Generator RAM (CGRAM) address.
			-- Processing time: ~40uS
			--
			-- `a_address': 6bit CGRAM address.
		require
			a_address_valid: (a_address & cgram_address_mask) = a_address
		do
			Result := set_cgram_address_ins | a_address
		ensure
			instruction_set: (Result & set_cgram_address_ins) = set_cgram_address_ins
			address_set: (Result & a_address) = a_address
		end

	set_ddram_address_op (a_address: NATURAL_8): NATURAL_8
			-- Returns binary encoded instruction for setting a Display Data RAM (DDRAM) address.
			-- Processing time: ~40uS
			--
			-- `a_address': 7bit DDRAM address.
		require
			a_address_valid: (a_address & ddram_address_mask) = a_address
		do
			Result := set_ddram_address_ins | a_address
		ensure
			instruction_set: (Result & set_ddram_address_ins) = set_ddram_address_ins
			address_set: (Result & a_address) = a_address
		end

feature -- Write operations

	write_to_register_op (a_register: NATURAL_8; a_strobe: NATURAL_8): NATURAL_8
			-- Set controller to write to register `a_register'
			--
			-- `a_register': register to set on controller.
			-- `a_strobe': pulse?
		require
			a_register_valid:
				a_register = read_write_register_data or
				a_register = read_write_register_instruction
			a_strobe_valid:
				a_strobe = read_write_strobe_on or
				a_strobe = read_write_strobe_off
		do
			Result := write_ins | a_register | a_strobe
		ensure
			instruction_set: (Result & write_ins) = write_ins
			register_set: (Result & a_register) = a_register
			strobe_set: (Result & a_strobe) = a_strobe
		end

feature -- Read operations

	read_from_register_op (a_register: NATURAL_8; a_strobe: NATURAL_8): NATURAL_8
			-- Set controller to read from register `a_register'
			--
			-- `a_register': register to set on controller.
			-- `a_strobe': pulse?
		require
			a_register_valid:
				a_register = read_write_register_data or
				a_register = read_write_register_instruction
			a_strobe_valid:
				a_strobe = read_write_strobe_on or
				a_strobe = read_write_strobe_off
		do
			Result := read_ins.bit_or (a_register).bit_or (a_strobe)
		ensure
			result_set: Result = read_ins.bit_or (a_register).bit_or (a_strobe)
		end

feature {NONE} -- Instructions

	entry_mode_ins: NATURAL_8 = 0b00000100
			-- Entry mode instruction code

	display_control_ins: NATURAL_8 = 0b00001000
			-- Display control instruction code

	cursor_display_shift_ins: NATURAL_8 = 0b00010000
			-- Cursor/display shift instruction code

	function_set_ins: NATURAL_8 = 0b00100000
			-- Display functionality instruction code

	set_cgram_address_ins: NATURAL_8 = 0b01000000
			-- Set CGRAM (Character Generator RAM) address instruction code

	set_ddram_address_ins: NATURAL_8 = 0b10000000
			-- Set DDRAM (Display Data RAM) address instruction code

	write_ins: NATURAL_8 = 0b00000000
			-- Write to display controller

	read_ins: NATURAL_8 = 0b10000000 -- Might be wrong!
			-- Read from display controller

feature -- Instruction Values

	function_font_5x7: NATURAL_8 = 0b00000000
	function_font_5x10: NATURAL_8 = 0b00000100
	function_lines_single: NATURAL_8 = 0b00000000
	function_lines_multi: NATURAL_8 = 0b00001000
	function_data_length_4bit: NATURAL_8 = 0b00000000
	function_data_length_8bit: NATURAL_8 = 0b00010000
			-- `function_set_ins_op' related constant values

	cursor_display_shift_left: NATURAL_8 = 0b00000100
	cursor_display_shift_right: NATURAL_8 = 0b00000000
	cursor_display_shift_cursor: NATURAL_8 = 0b00000000
	cursor_display_shift_display: NATURAL_8 = 0b0001000
			-- `cursor_display_shift_ins_op' related constant values

	entry_shift_none: NATURAL_8 = 0b00000000
	entry_shift_display: NATURAL_8 = 0b00000001
	entry_move_decrement_cursor: NATURAL_8 = 0b00000000
	entry_move_increment_cursor: NATURAL_8 = 0b00000010
			-- `entry_mode_ins_op' related constant values

	display_blink_cursor_off: NATURAL_8 = 0b00000000
	display_blink_cursor_on: NATURAL_8 = 0b00000001
	display_cursor_off: NATURAL_8 = 0b00000000
	display_cursor_on: NATURAL_8 = 0b00000010
	display_off: NATURAL_8 = 0b00000000
	display_on: NATURAL_8 = 0b00000100
			-- `display_control_ins_op' related constant values

	read_write_strobe_off: NATURAL_8 = 0b00000000
	read_write_strobe_on: NATURAL_8 = 0b00000001
	read_write_register_instruction: NATURAL_8 = 0b00000000
	read_write_register_data: NATURAL_8 = 0b00000100
			-- `write_to_register_op' and `read_from_register_op' related constant values

feature -- Bitmasks

	cgram_address_mask: NATURAL_8 = 0b00111111
			-- Bit mask used for setting CGRAM address with `set_cgram_address_op'

	ddram_address_mask: NATURAL_8 = 0b01111111
			-- Bit mask used for setting DDRAM address with `set_ddram_address_op'

end