Skip to content
Copyright © 2024 4D Systems

ViSi-Genie Magic: Comms 'NIL' Option

Details
Number 4D-AN-00274
Difficulty Medium
Supported Processors DIABLO-16, PIXXI-28, PIXXI-44, PICASO
Supported Environments ViSi-Genie

Description

This application note discusses the use of the 'nil' option for Comms selection. This option is useful if you do not want to use or if you need to customize the ViSi-Genie protocol for your application.

The Comms -Nil- option allows you to either turn off the ViSi-Genie command protocol or modify it according to your needs.

This application requires the PRO version of Workshop4 to access the ViSi-Genie Magic feature.

Document

Prerequisites

It is recommended to have read and tried the following application notes including their own prerequisites prior to learning this application.

Application Overview

To communicate with 4D Systems displays on ViSi-Genie environment using UART serial, there are 3 options that we can use.

  1. COM0 which is the using TX0 and RX0. This is also used when programming the displays.
  2. COM1 which can be used from the additional TX1 and RX1 pins available. For DIABLO-16 displays, RX1 and TX1 can be assigned (refer to DIABLO-16 display datasheet for supported pins).
  3. NIL – which stops the comms.

Setting the comms to 'nil' will stop the display from sending the Genie protocol. In this case, you can use magic code to modify the Send Report function that the display will send to the host controller. For example, if you want to add a specific start character or other information from the host controller.

You can also make your own function to capture any information from the host controller.

Setup Procedure

For instructions on how to launch Workshop4, how to open a ViSi-Genie project, and how to change the target display, kindly refer to the section Setup Procedure of the application notes:

There is an example from the Wokrshop4 IDE called GenieCommsManual that shows how to use the Nil option. To open, go to, File > Samples > PICASO/Diablo/PIXXI ViSi-Genie > GenieCommsManual.

This application note discusses the procedure on how to create a Comms -Nil- ViSi-Genie project similar to the WS4 project specified.

Creating a New Project

For instructions on how to create a new ViSi project, please refer to the section Create a New Project of the application notes:

Design the Project

Setting Comms to NIL

After creating a new ViSi-Genie project and designing your user interface, you can set the Comms option to -Nil- by going to Project Menu > Comms then from the dropdown select the -Nil- option.

nil_option

Note

This option requires that the SendReport function is added manually to a MagicCode. The MagicCode insert point should be set to Constants/Global/Data.

Constants/Global/Data

Add MagicCode by selecting the MagicCode as shown:

add magic code

Open the code MagicCode0.inc by clicking ... button.

open_mc0

The MagicCode0 file will open and show an empty 4DGL code.

When using Comms -Nil- option, it is required that the SendReport function is added to Global code.

//
// SendReport is always needed, if you never send reports, this routine should be 'null'
//
func SendReport(var id, var objt, var objn, var val)
    // By making this empty (null), Report Event in widget event options does nothing
endfunc

The SendReport function should take four (4) arguments:

id

This is the command ID which is either REPORT_EVENT or REPORT_OBJ. In most cases, REPORT_EVENT is used as it is triggered by touch inputs from widgets.

objt

This is the type of widget the triggered the report.

objn

This is the index number of the widget.

val

This is the new value of the widget.

The SendReport function can be modified by adding information to the packet that will be sent to the host or make it 'null' if you do not use send report.

For this application note, the ViSi-Genie protocol is added manually to demonstrate how to customize the reporting after disabling.

#CONST
    CMDLenMAX       80  // 80 is used for 'default' max string length of 75
    CommsBuffLen    40  // 40 is used for 'default' max string length of 75 
                        //    (i.e. half of CMDLenMAX)
#END

var comRX[CommsBuffLen], cmd[CMDLenMAX] ;
var InputCS, OutputCS ;

func seroutCS(var op)
    serout(op) ;
    OutputCS ^= op ;
endfunc

func nak0()
    serout(NAK) ;
    InputCS := 0 ;
endfunc

func seroutOcs()
    serout(OutputCS) ;
    OutputCS := 0 ;
endfunc

//
// SendReport is always needed, if you never send reports, this routine should be 'null'
//
func SendReport(var id, var objt, var objn, var val)
    seroutCS(id) ;
    seroutCS(objt) ;
    seroutCS(objn) ;
    seroutCS(val >> 8) ; // first 8 bits
    seroutCS(val) ;
    seroutOcs() ;
endfunc

PreGenieInit

Since the project aims to manually add the ViSi-Genie Serial protocol, the Serial comms needs to initialized manually as well. To do this, add another MagicCode to the project and set its insert point to PreGenieInit.

add magic code

Open the code MagicCode1.inc by clicking ... button.

open_mc1

The MagicCode1 file will open and show an empty 4DGL code.

You can put additional variables and functions needed by the application. In this case, two variables used by default comms are included. Initialize the comms, set baudrate and TXBuffer.

//
// Two variables used by the default comms. You might not want/need them,
// or you might want them as global variables.
//
var comTX[50], cmdi ;

com_Init(comRX,CMDLenMAX,0);
com_SetBaud(COM0,960);
com_TXbuffer(comTX, 100, 0);

Mainloop

Finally, to complete the manually added the project aims to manually add the ViSi-Genie Serial protocol, the commands coming from the host controller needs to be handled manually as well. To do this, add another MagicCode to the project and set its insert point to MainLoop.

add magic code

Open the code MagicCode2.inc by clicking ... button.

open_mc2

The MagicCode2 file will open and show an empty 4DGL code.

In the main loop, we can add handling of commands coming from the host controller as shown:

//
// Standard/simplified comms input,
// does not handle Magic Objets, Unicode Strings, strings, labels, inherent widgets,
// and internal buttons.... Just a simple example!
//

// check comms for command, how to NAK invalid command
if (com_Count() != 0)
    i := serin() ;
    InputCS ^= i ;               // update checksum
    cmd[cmdi++] := i ;
        if ((cmd[0] == READ_OBJ) && (cmdi == 4))
        if (InputCS)
            nak0() ;
        else
            ReadObject(cmd[1], cmd[2]) ;
        endif
        cmdi := 0 ;
    else if ((cmd[0] == WRITE_OBJ) && (cmdi == 6)) // 6 byte write command (gen option)
        if (InputCS)
            nak0() ;
        else
            WriteObject(cmd[1], cmd[2], cmd[3] << 8 + cmd[4]) ;
            serout(ACK) ;
        endif
        cmdi := 0 ;
    else if ((cmd[0] == WRITE_CONTRAST) && (cmdi == 3))
        if (InputCS)
            nak0() ;
        else
            gfx_Contrast(cmd[1]) ;
            serout(ACK) ;
        endif
        cmdi := 0 ;
    else if (cmdi == 6)    // we have 6 bytes and we've gotten here -> something wrong
        nak0() ;
        cmdi := 0 ;
    endif
endif   // a character is available

Build and Upload the Project

To test this project, add some input widgets (buttons, slider or knobs) and set the events to Report Event as you would in a simple ViSi-Genie project. You can refer to the application note ViSi-Genie: onChanging and onChanged Events for more information.

For instructions on how to build and upload a ViSi-Genie project to the target display, please refer to the section Build and Upload the Project of the application note

The uLCD-32PTU and/or the uLCD-35DT display modules are commonly used as examples, but the procedure is the same for other ViSi-Genie compatible displays. For this application note, gen4-uLCD-35P4T was used.