PicShell - Annotation guide


PicShell use annotation to interact with the simulator, for directives, inputs and outputs. Annotation has no special meaning for JAL, it's seen as a normal comment.
Both --@ or ;@ can be used to specifie annotations



Directives annotation

AnnotationPurposeSyntax
@use_virtual_delay Tells PicShell to treat delay internally in python, This result in a faster execution for real-time simulation. ;@use_virtual_delay
@no_debug Tells PicShell to not ignore an include while debuging (code is still executed, but will not appear in the JAL debug windows.

That can be usefull on "trusted code", if we don't go into the detail of delay implementation for instance.		 ;@no_debug 16f877_inc

or

include pjal_877 ;@no_debug
@no_debug_all Tells PicShell to not ignore all includes while debuging (code is still executed, but will not appear in the JAL debug windows.) ;@no_debug_all
@debug Tells PicShell to include an include lib while debuging (only useful in conjonction with @no_debug_all, so that we can tell picshell which lib to include instead of which lib to ignore ) ;@debug 16f877_inc

or

include pjal_877 ;@debug
@assertEquals Tells PicShell to check a variable value against a reference value test(variable_name);@assertEquals ref_value test_label

Example : See file "examples/unitTest.jal" in your picshell directory.




Inputs annotation

AnnotationPurposeSyntax
@mpu Momentary Pull-Up switch
 Without alias
;@mpu label pin_a0

With an alias :
var bit bt0 is pin_a0 ;@mpu label

Sample code :
;@no_debug 16f877_inc
include pjal_877 ;@no_debug
include pic_general ;@no_debug
pragma target clock 4_000_000
pragma target fuses 0x3F32
ADCON1 = 0x07 -- disable A/D

;@mpu button1 pin_a0
;@watch_bin 0x6 port_b

port_A_direction = all_input
port_B_direction = all_output

PORTB = 0
forever loop
	if (pin_a0 == low) then
		PORTB = 1
	else
		PORTB = 0
	end if
end loop
Output :

@mpd Momentary Pull-Down switch
 Without alias
;@mpd label pin_a0

With an alias :
var bit bt0 is pin_a0 ;@mpd label

Sample code :
;@no_debug 16f877_inc
include pjal_877 ;@no_debug
include pic_general ;@no_debug
pragma target clock 4_000_000
pragma target fuses 0x3F32
ADCON1 = 0x07 -- disable A/D

;@mpd button1 pin_a0
;@watch_bin 0x6 port_b

port_A_direction = all_input
port_B_direction = all_output

PORTB = 0
forever loop
	if (pin_a0 == high) then
		PORTB = 1
	else
		PORTB = 0
	end if
end loop
@ppu Permanent Pull-Up switch
 Without alias
;@ppu label pin_a0

With an alias :
var bit bt0 is pin_a0 ;@ppu label

Sample code :
;@no_debug 16f877_inc
include pjal_877 ;@no_debug
include pic_general ;@no_debug
pragma target clock 4_000_000
pragma target fuses 0x3F32
ADCON1 = 0x07 -- disable A/D

;@ppu button1 pin_a0
;@watch_bin 0x6 port_b

port_A_direction = all_input
port_B_direction = all_output

PORTB = 0
forever loop
	if (pin_a0 == low) then
		PORTB = 1
	else
		PORTB = 0
	end if
end loop
Outputs :
@ppd Permanent Pull-Down switch
 Without alias
;@ppd label pin_a0

With an alias :
var bit bt0 is pin_a0 ;@ppd label

Sample code :
;@no_debug 16f877_inc
include pjal_877 ;@no_debug
include pic_general ;@no_debug
pragma target clock 4_000_000
pragma target fuses 0x3F32
ADCON1 = 0x07 -- disable A/D

;@ppd button1 pin_a0
;@watch_bin 0x6 port_b

port_A_direction = all_input
port_B_direction = all_output

PORTB = 0
forever loop
	if (pin_a0 == high) then
		PORTB = 1
	else
		PORTB = 0
	end if
end loop
@pot Potentiometer

This component is useful for testing the A/D Converter 		Without alias
;@pot label pin_a0

With an alias :
var bit bt0 is pin_a0 ;@pot label

Example : See file "examples/adc_example.jal" in your picshell directory.
@byteSender Send some bytes to the PIC hardware serial UART
PicShell is somehow limited in this kind of simulation, and is not sensible to the serail settings like baudrate for instance. 		;@byteSender (take no parameter)

Note : In the user interface, mutliple bytes can be send using the , separator.
@asciiSender Same as @byteSender except that the user interface accept text instead of numbers, may be useful for LCD testing ;@asciiSender (take no parameter)

Example : See file "examples/uart_lcd_example.jal" in your picshell directory.
@midiSender Deprecated, A composant that send MIDI "Program change" message.

@byteSender may be used instead as it is more generic.		 ;@midiSender (take no parameter)

Example : See file "examples/midi_in_example.jal" in your picshell directory.
@labelIn a simple label, that while stack in the "in" column Sample usage : ;@labelIn text (optional)




Outputs annotation

AnnotationPurposeSyntax
@watch "Realtime" watch to one address, displayed as decimal ;@watch address label
  • address : port address
  • label : a label [optional]
Sample usage : ;@watch 6 this_is_port_b
Example : See file "examples/first_example.jal" in your picshell directory.
@watch_bin "Realtime" watch on a resister. display as binary ;@watch_bin address label
  • address : port address
  • label : a label [optional]
Sample usage : ;@watch_bin 6 this_is_port_b
Example : See file "examples/first_example.jal" in your picshell directory.
@watch_hex "Realtime" watch on a resister. display as hexadecimal ;@watch_hex address label
  • address : port address
  • label : a label [optional]
Sample usage : ;@watch_hex 6 this_is_port_b
Example : See file "examples/first_example.jal" in your picshell directory.
@led
@led_red
@led_green
@led_orange
@led_yellow
@led_green
@led_blue
 Display a led
 ;@led bit label
  • bit : bit to drive the led (bit can be specified like these : 0x7:4, PORTX:2 or pin_xx)
  • label : a label [optional]

;@led_red ;@led_orange ;@led_yellow ;@led_green ;@led_blue
are same as ;@led, but use a gif instead of a text

Sample usage : ;@led pin_c0 a_label
Example : See file "examples/led_example.jal" in your picshell directory.
@upDownCounter Counter, that increment on impulsion.
Can be used to simulate "digital potentiometers".		 ;@upDownCounter address,enable_bit,impulsion_bit,up_down_bit,max_value label
  • address : port address
  • enable_bit : allow to have several counter one the same port, if false, the counter won't increment
  • impulsion_bit : bit used to transmit impulsion
  • up_down_bit : bit set means increment, bit clear means decrement
  • max_value : max value where the counter stop to increment. (the counter is not cyclic). min value is 0
  • label : a label [optional]
Limitations : all paramters refer to the same address
Sample usage : ;@upDownCounter 0x6,0,1,2,10 counter1
Example : See file "examples/counter_example.jal" in your picshell directory.
@dual7seg Dual 7 segments display based on a CD4511 / CD4518 driver circuit. ;@dual7seg address,resetBit,digit1Bit,digit2Bit label
  • address : port address
  • resetBit : if set display (and internal counter) get back to 00
  • digit1Bit : bit used to transmit impulsions to increment digit1
  • digit2Bit : bit used to transmit impulsions to increment digit2
  • label : a label [optional]
Limitations : all paramters refer to the same address
Sample usage : ;@dual7seg 0x6,0,1,2 counter
Example : See file "examples/dual7seg_example.jal" in your picshell directory.
@lcd4bit Limited HD44780, 4bits mode LCD.

This componant is mainly used for internal testing, and is really limited both in fonctionality and configuration for now. 		;@lcd4bit address(,nbchar) label
  • address : port address
  • nbchar : char per line, [optional, default is 16]
  • label : a label [optional]
Hardcoded config :

  • HD44780_b4 : address:0
  • HD44780_b5 : address:1
  • HD44780_b6 : address:2
  • HD44780_b7 : address:3
  • HD44780_DataCmd : address:4
  • HD44780_Enable : address:5
Limitations : Only port address is configurable for now
Sample usage : ;@lcd4bit 0x6 My_LCD
Examples : "example/lcd_example.jal" and "example/uart_lcd_example.jal" in your picshell directory.
@uartReciever Serial reciever that may be used to test UART output. ;@uartReciever  (take no parameter)

Sample usage : ;@uartReciever
Example : "example/midi_out_example.jal" in your picshell directory.
@labelOut a simple label, that while stack in the "out" column Sample usage : ;@labelOut text (optional)