blib/lib/Device/Chip/NoritakeGU_D.pm

filter: Statementstmt 89.5% 240 / 268 Branchbran 30.7% 8 / 26 Conditioncond 26.3% 5 / 19 MC/DCmcdc 0.0% 0 / 11 Subroutinesub 83.6% 46 / 55 Podpod 56.0% 14 / 25 totaltotal 77.4% 313 / 404 CC 23 SCAR 15.4
CC
23
Cov
81%
set_font_magnification
30.0
realtime_image_display_lines
20.0
power
6.0
CRAP 4.6
↑ Summary
1 # You may distribute under the terms of either the GNU General Public License
2 # or the Artistic License (the same terms as Perl itself)
3 #
4 # (C) Paul Evans, 2020-2023 -- leonerd@leonerd.org.uk
5  
6 8 ▶use v5.26; # signatures
Subroutine BEGIN: called CC=1 SCAR=0.0
7 8 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 8 ▶use Object::Pad 0.800;
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10 package Device::Chip::NoritakeGU_D 0.06;
11 class Device::Chip::NoritakeGU_D
12 1 ▶ :isa(Device::Chip);
Subroutine BEGIN: called CC=1 SCAR=0.0
13  
14 8 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
15  
16 8 ▶use Future::AsyncAwait;
Subroutine BEGIN: called CC=1 SCAR=0.0
17 8 ▶use List::Util qw( first );
Subroutine BEGIN: called CC=1 SCAR=0.0
18  
19 =encoding UTF-8
20  
21 =head1 NAME
22  
23 C<Device::Chip::NoritakeGU_D> - chip driver for F<Noritake> F<GU-D> display modules
24  
25 =head1 SYNOPSIS
26  
27 use Device::Chip::NoritakeGU_D;
28 use Future::AsyncAwait;
29  
30 my $chip = Device::Chip::NoritakeGU_D->new( interface => "UART" );
31 await $chip->mount( Device::Chip::Adapter::...->new );
32  
33 await $chip->text( "Hello, world!" );
34  
35 =head1 DESCRIPTION
36  
37 This L<Device::Chip> subclass provides communication to a display module in
38 the F<GU-D> family by F<Noritake>.
39  
40 The reader is presumed to be familiar with the general operation of this chip;
41 the documentation here will not attempt to explain or define chip-specific
42 concepts or features, only the use of this module to access them.
43  
44 =cut
45  
46 =head1 CONSTRUCTOR
47  
48 =cut
49  
50 =head2 new
51  
52 $chip = Device::Chip::NoritakeGU_D->new(
53 interface => $iface,
54 ...
55 )
56  
57 Constructs a new driver instance for the given interface type. The type must
58 be one of C<UART>, C<I2C> or C<SPI>.
59  
60 =cut
61  
62 8 my %INTERFACES = (
63 UART => 1, I2C => 1, SPI => 1,
64 );
65  
66 8 field $_protocol :param(interface);
67 8 field $_interface;
68  
69 ADJUST
70 {
71 $INTERFACES{$_protocol} or
72 croak "Unrecognised interface type '$_protocol'";
73  
74 my $iface_class = __PACKAGE__."::_Iface::$_protocol";
75 $_interface = $iface_class->new;
76 }
77  
78 7 ▶method PROTOCOL { $_protocol }
Subroutine PROTOCOL: called CC=1 SCAR=0.0
Pod undocumented
79  
80 7 ▶*UART_options = *I2C_options = *SPI_options = method { $_interface->options };
Subroutine __ANON__: called CC=1 SCAR=0.0
81  
82 # passthrough
83 method power
84 0 ▶{
Subroutine power: not called CC=2 SCAR=17.9
Pod undocumented
85 0 ▶ return $self->protocol->power( @_ ) if $self->protocol->can( "power" );
Branch: 1 branch
BranchTrueFalseTotal
if $self->protocol->can("power") 0 0 0
86 0 return Future->done;
87 8 }
88  
89 7 ▶method mount ( $adapter, %params )
Subroutine mount: called CC=1 SCAR=0.0
Pod documented
90 {
91 7 $_interface->mountopts( \%params );
92  
93 7 return $self->SUPER::mount( $adapter, %params );
94 8 }
95  
96 15 ▶method write { $_interface->write( $self, @_ ) }
Subroutine write: called CC=1 SCAR=0.0
Pod undocumented
97 5 ▶method read { $_interface->read ( $self, @_ ) }
Subroutine read: called CC=1 SCAR=0.0
Pod undocumented
98  
99 6 ▶method write_us { $self->write( pack "C*", 0x1F, @_ ) }
Subroutine write_us: called CC=1 SCAR=0.0
Pod undocumented
100  
101 =head1 METHODS
102  
103 The following methods documented in an C<await> expression return L<Future>
104 instances.
105  
106 =cut
107  
108 =head2 text
109  
110 await $chip->text( $str );
111  
112 Draw text at the cursor position.
113  
114 =cut
115  
116 3 ▶async method text ( $text )
Subroutine text: called CC=2 SCAR=7.0
Pod documented
117 3 {
118 # Don't allow C0 controls
119 3 ▶ $text =~ m/[\x00-\x1F]/ and
Branch: 1 branch
BranchTrueFalseTotal
$text =~ /[\x00-\x1F]/u and croak("Invalid characters for ->text") 0 3 3
120 croak "Invalid characters for ->text";
121  
122 3 await $self->write( $text );
123 8 }
124  
125 16 ▶sub BOOL_COMMAND ( $name, @bytes )
Subroutine BOOL_COMMAND: called CC=1 SCAR=0.0
Pod undocumented
126 {
127 16 my $lastbyte = pop @bytes;
128  
129 8 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
130 1 ▶ *$name = method ( $on ) {
Subroutine __ANON__: called CC=1 SCAR=0.0
131 1 $self->write_us( @bytes, $lastbyte + !!$on );
132 16 };
133 }
134  
135 16 ▶sub INT_COMMAND ( $name, $min, $max, @bytes )
Subroutine INT_COMMAND: called CC=1 SCAR=0.1
Pod undocumented
136 {
137 16 my $shortname = ( split m/_/, $name )[-1];
138  
139 16 my $lastbyte = pop @bytes;
140  
141 8 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
142 1 ▶ *$name = method ( $value ) {
Subroutine __ANON__: called CC=3 SCAR=11.6
143 1 ▶ $value >= $min and $value <= $max or
Branch: 1 branch
BranchTrueFalseTotal
$value >= $min and $value <= $max or croak("Invalid $shortname for ->$name") 1 0 1
Condition33%1/3
$value >= $min and $value <= $max
!ll&&!rl&&r
001
MC/DC0%0/2
$value >= $min and $value <= $max
$value >= $min $value <= $max
Truth table33%1/3
A and B
A= $value >= $minB= $value <= $max
ABresult
0X0
100
111
144 croak "Invalid $shortname for ->$name";
145  
146 1 $self->write_us( @bytes, $lastbyte + $value );
147 16 };
148 }
149  
150 24 ▶sub ENUM_COMMAND ( $name, $values, @bytes )
Subroutine ENUM_COMMAND: called CC=1 SCAR=0.0
Pod undocumented
151 {
152 24 my @values = @$values;
153  
154 24 my $shortname = ( split m/_/, $name )[-1];
155  
156 24 my $lastbyte = pop @bytes;
157  
158 8 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
159 1 ▶ *$name = method ( $value ) {
Subroutine __ANON__: called CC=2 SCAR=7.0
160 1 ▶ defined( my $index = first { $values[$_] eq $value } 0 .. $#values ) or
Subroutine __ANON__: called CC=1 SCAR=0.2
Branch: 1 branch
BranchTrueFalseTotal
defined(my $index = &first(sub { $values[$_] eq $value; } , 0 .. $#values)) or croak("Invalid $shortname for ->$name") 1 0 1
161 croak "Invalid $shortname for ->$name";
162  
163 1 $self->write_us( @bytes, $lastbyte + $index );
164 24 };
165 }
166  
167 =head2 cursor_left
168  
169 =head2 cursor_right
170  
171 =head2 cursor_home
172  
173 await $chip->cursor_left;
174 await $chip->cursor_right;
175  
176 await $chip->cursor_linehome;
177  
178 await $chip->cursor_home;
179  
180 Move the cursor left or right one character position, to the beginning of the
181 line, or to the home position (top left corner).
182  
183 =cut
184  
185 0 ▶method cursor_left { $self->write( "\x08" ) }
Subroutine cursor_left: not called CC=1 SCAR=1.2
Pod documented
186 0 ▶method cursor_right { $self->write( "\x09" ) }
Subroutine cursor_right: not called CC=1 SCAR=1.2
Pod documented
187 0 ▶method cursor_linehome { $self->write( "\x0D" ) }
Subroutine cursor_linehome: not called CC=1 SCAR=1.2
Pod undocumented
188 0 ▶method cursor_home { $self->write( "\x0B" ) }
Subroutine cursor_home: not called CC=1 SCAR=1.2
Pod documented
189  
190 =head2 cursor_goto
191  
192 await $chip->cursor_goto( $x, $y );
193  
194 Moves the cursor to the C<$x>'th column of the C<$y>'th line (zero-indexed).
195  
196 =cut
197  
198 1 ▶method cursor_goto ( $x, $y )
Subroutine cursor_goto: called CC=1 SCAR=0.0
Pod documented
199 {
200 # TODO: Bounds-check $x, $y
201  
202 1 $self->write( pack "C C S< S<", 0x1F, 0x24, $x, $y );
203 8 }
204  
205 =head2 linefeed
206  
207 await $chip->linefeed;
208  
209 Move the cursor down to the next line.
210  
211 =cut
212  
213 0 ▶method linefeed { $self->write( "\x0A" ) }
Subroutine linefeed: not called CC=1 SCAR=1.2
Pod documented
214  
215 =head2 clear
216  
217 $chip->clear
218  
219 Clear the display.
220  
221 =cut
222  
223 3 ▶method clear { $self->write( "\x0C" ) }
Subroutine clear: called CC=1 SCAR=0.0
Pod documented
224  
225 =head2 select_window
226  
227 await $chip->select_window( $win );
228  
229 Select the main window (when C<$win> is 0), or one of the four numbered
230 sub-windows.
231  
232 =cut
233  
234 8 INT_COMMAND select_window => 0, 4,
235 0x10;
236  
237 =head2 initialise
238  
239 $chip->initialise
240  
241 Reset all settings to their default values.
242  
243 =cut
244  
245 0 ▶method initialise { $self->write( "\x1B\x40" ) }
Subroutine initialise: not called CC=1 SCAR=1.2
Pod documented
246  
247 =head2 set_cursor_visible
248  
249 await $chip->set_cursor_visible( $bool );
250  
251 Set whether the cursor is visible.
252  
253 =cut
254  
255 8 BOOL_COMMAND set_cursor_visible =>
256 0x43, 0x00;
257  
258 =head2 set_brightness
259  
260 await $chip->set_brightness( $val );
261  
262 Set the display brightness, from 1 to 8.
263  
264 =cut
265  
266 8 INT_COMMAND set_brightness => 1, 8,
267 0x58, 0x00;
268  
269 =head2 set_reverse
270  
271 await $chip->set_reverse( $bool );
272  
273 Sets whether subsequent text will be rendered in "reverse video" (clear pixels
274 on a set background) effect.
275  
276 =cut
277  
278 8 BOOL_COMMAND set_reverse =>
279 0x72, 0x00;
280  
281 =head2 set_write_mixture_display_mode
282  
283 await $chip->set_write_mixture_display_mode( $mode );
284  
285 Set the combining mode for newly-added display content. C<$mode> must be one
286 of
287  
288 set or and xor
289  
290 =cut
291  
292 8 ENUM_COMMAND set_write_mixture_display_mode => [qw( set or and xor )],
293 0x77, 0x00;
294  
295 =head2 set_font_size
296  
297 await $chip->set_font_size( $size );
298  
299 Set the font size. C<$size> must be one of
300  
301 5x7 8x16
302  
303 =cut
304  
305 8 ENUM_COMMAND set_font_size => [qw( 5x7 8x16 )],
306 0x28, 0x67, 0x01, 0x01;
307  
308 =head2 set_font_width
309  
310 await $chip->set_font_width( $width );
311  
312 Set the font width. C<$width> must be one of
313  
314 fixed fixed2 prop prop2
315  
316 =cut
317  
318 8 ENUM_COMMAND set_font_width => [qw( fixed fixed2 prop prop2 )],
319 0x28, 0x67, 0x03, 0x00;
320  
321 =head2 set_font_magnification
322  
323 await $chip->set_font_magnification( $xscale, $yscale );
324  
325 Set the font scaling factor. C<$xscale> must be between 1 to 4, and
326 C<$yscale> must be 1 or 2.
327  
328 =cut
329  
330 0 ▶method set_font_magnification ( $x, $y )
Subroutine set_font_magnification: not called CC=5 SCAR=34.0
Pod documented
331 {
332 0 ▶ $x >= 1 and $x <= 4 or croak "Invalid x scale";
Branch: 1 branch
BranchTrueFalseTotal
$x >= 1 and $x <= 4 or croak("Invalid x scale") 0 0 0
Condition0%0/3
$x >= 1 and $x <= 4
!ll&&!rl&&r
000
MC/DC0%0/2
$x >= 1 and $x <= 4
$x >= 1 $x <= 4
Truth table0%0/3
A and B
A= $x >= 1B= $x <= 4
ABresult
0X0
100
111
333 0 ▶ $y >= 1 and $y <= 2 or croak "Invalid y scale";
Branch: 1 branch
BranchTrueFalseTotal
$y >= 1 and $y <= 2 or croak("Invalid y scale") 0 0 0
Condition0%0/3
$y >= 1 and $y <= 2
!ll&&!rl&&r
000
MC/DC0%0/2
$y >= 1 and $y <= 2
$y >= 1 $y <= 2
Truth table0%0/3
A and B
A= $y >= 1B= $y <= 2
ABresult
0X0
100
111
334  
335 0 $self->write_us( 0x28, 0x67, 0x40, $x, $y );
336 8 }
337  
338 1 ▶method _realtime_image_display ( $width, $height, $bytes )
Subroutine _realtime_image_display: called CC=1 SCAR=0.0
339 {
340 1 $self->write( "\x1F\x28\x66\x11" . pack "S< S< C a*",
341 $width, $height, 1, $bytes,
342 );
343 8 }
344  
345 =head2 realtime_image_display_columns
346  
347 await $chip->realtime_image_display_columns( @columns );
348  
349 Sends a bitmapped image to the display, at the cursor position. The cursor is
350 not moved.
351  
352 C<@columns> should be a list of strings of equal length, containing bytes of
353 pixel data to represent each vertical column of the image content.
354  
355 =cut
356  
357 1 ▶method realtime_image_display_columns ( @columns )
Subroutine realtime_image_display_columns: called CC=4 SCAR=14.0
Pod documented
358 {
359 1 ▶ @columns or croak "Expected at least 1 column";
Branch: 1 branch
BranchTrueFalseTotal
@columns or croak("Expected at least 1 column") 1 0 1
360 1 my $height = length $columns[0];
361 1 ▶ $height == length $_ or croak "Expected all columns of equal length" for @columns[1..$#columns];
Branch: 1 branch
BranchTrueFalseTotal
$height == length $_ or croak("Expected all columns of equal length") 2 0 2
362  
363 1 my $bytes = join "", @columns;
364  
365 1 $self->_realtime_image_display( scalar @columns, $height, $bytes );
366 8 }
367  
368 0 ▶method realtime_image_display_lines ( @lines )
Subroutine realtime_image_display_lines: not called CC=4 SCAR=30.0
Pod undocumented
369 {
370 0 ▶ @lines or croak "Expected at least 1 line";
Branch: 1 branch
BranchTrueFalseTotal
@lines or croak("Expected at least 1 line") 0 0 0
371 0 my $width = length $lines[0];
372 0 ▶ $width == length $_ or croak "Expected all lines of equal length" for @lines[1..$#lines];
Branch: 1 branch
BranchTrueFalseTotal
$width == length $_ or croak("Expected all lines of equal length") 0 0 0
373  
374 # Restripe the data in vertical strips
375 my $bytes = join "", map {
376 0 my $col = $_;
377 0 map { substr( $lines[$_], $col, 1 ) } 0 .. $#lines
378 } 0 .. $width-1;
379  
380 0 $self->_realtime_image_display( $width, scalar @lines, $bytes );
381 8 }
382  
383 =head2 set_gpio_direction
384  
385 await $chip->set_gpio_direction( $dir );
386  
387 Configure the GPIO pins for input or output. C<$dir> is bitmask of four bits.
388 Low bits correspond to input, high bits to output.
389  
390 =cut
391  
392 1 ▶async method set_gpio_direction ( $dir )
Subroutine set_gpio_direction: called CC=1 SCAR=0.0
Pod documented
393 1 {
394 1 await $self->write_us( 0x28, 0x70, 0x01, 0x00, $dir & 0x0F );
395 8 }
396  
397 =head2 set_gpio_output
398  
399 await $chip->set_gpio_output( $value );
400  
401 Write the value to the GPIO pins.
402  
403 =cut
404  
405 1 ▶async method write_gpio ( $value )
Subroutine write_gpio: called CC=1 SCAR=0.0
Pod undocumented
406 1 {
407 1 await $self->write_us( 0x28, 0x70, 0x10, 0x00, $value & 0x0F );
408 8 }
409  
410 =head2 read_gpio
411  
412 $value = await $chip->read_gpio;
413  
414 Returns the current state of the GPIO pins.
415  
416 =cut
417  
418 async method read_gpio
419 1 ▶{
Subroutine read_gpio: called CC=4 SCAR=15.9
Pod documented
420 1 await $self->write_us( 0x28, 0x70, 0x20, 0x00 );
421 1 my ( $header, $id1, $id2, $value ) = unpack "C4", await $self->read( 4 );
422  
423 1 ▶ croak "Expected 0x28 0x70 0x20" unless $header == 0x28 and
Branch: 1 branch
BranchTrueFalseTotal
unless $header == 40 and $id1 == 112 and $id2 == 32 0 1 1
Condition33%2/6
$header == 40 and $id1 == 112 and $id2 == 32
!ll&&!rl&&r
001
$header == 40 and $id1 == 112
!ll&&!rl&&r
001
MC/DC0%0/3
$header == 40 and $id1 == 112 and $id2 == 32
$header == 40 $id1 == 112 $id2 == 32
Truth table25%1/4
A and B and C
A= $header == 40B= $id1 == 112C= $id2 == 32
ABCresult
0XX0
10X0
1100
1111
424 $id1 == 0x70 and $id2 == 0x20;
425  
426 1 return $value;
427 8 }
428  
429 =head2 read_touchswitches
430  
431 $switches = await $chip->read_touchswitches;
432  
433 Reads the status of the panel touch switches. Returns a hash reference whose
434 keys are the names of the touch areas (C<SW1>, C<SW2>, ...) and values are
435 booleans indicating whether that area currently detects a touch.
436  
437 =cut
438  
439 async method read_touchswitches
440 1 ▶{
Subroutine read_touchswitches: called CC=3 SCAR=11.2
Pod documented
441 1 await $self->write( "\x1F\x4B\x10" );
442  
443 1 my ( $header, $len, $switches ) = unpack "C C S>", await $self->read( 4 );
444 1 ▶ croak sprintf "Expected header = 0x10; got 0x%02X", $header if $header != 0x10;
Branch: 1 branch
BranchTrueFalseTotal
if $header != 16 0 1 1
445 1 ▶ croak "Expected length=2, got $len" if $len != 2;
Branch: 1 branch
BranchTrueFalseTotal
if $len != 2 0 1 1
446  
447 return {
448 1 map +("SW$_", $switches & ( 2 ** ( $_-1 ) )), 1 .. 16
449 };
450 8 }
451  
452 # Interface helpers
453  
454 class Device::Chip::NoritakeGU_D::_Iface::UART {
455 8 ▶ use constant DEFAULT_BAUDRATE => 38400;
Subroutine BEGIN: called CC=1 SCAR=0.0
456  
457 8 field $_baudrate;
458  
459 5 ▶ method mountopts ( $params )
Subroutine mountopts: called CC=2 SCAR=7.0
460 {
461 5 ▶ $_baudrate = delete $params->{baudrate} // DEFAULT_BAUDRATE;
Condition50%1/2
delete $params->{"baudrate"} // 38400
l!l
05
MC/DC0%0/1
delete $params->{"baudrate"} // 38400
delete $params->{"baudrate"}
Truth table50%1/2
A
A= delete $params->{"baudrate"}
Aresult
11
00
462 8 }
463  
464 method options
465 5 ▶ {
Subroutine options: called CC=1 SCAR=0.0
466 return (
467 5 baudrate => $_baudrate,
468 );
469 8 }
470  
471 11 ▶ async method write ( $chip, $bytes )
Subroutine write: called CC=1 SCAR=0.0
472 11 {
473 11 await $chip->protocol->write( $bytes );
474 8 }
475  
476 3 ▶ async method read ( $chip, $len )
Subroutine read: called CC=1 SCAR=0.0
477 3 {
478 3 return await $chip->protocol->read( $len );
479 8 }
480 }
481  
482 8 class Device::Chip::NoritakeGU_D::_Iface::I2C {
483 8 ▶ use constant DEFAULT_ADDR => 0x50;
Subroutine BEGIN: called CC=1 SCAR=0.0
484  
485 8 field $_addr;
486  
487 1 ▶ method mountopts ( $params )
Subroutine mountopts: called CC=2 SCAR=7.0
488 {
489 1 ▶ $_addr = delete $params->{addr} // DEFAULT_ADDR;
Condition50%1/2
delete $params->{"addr"} // 80
l!l
01
MC/DC0%0/1
delete $params->{"addr"} // 80
delete $params->{"addr"}
Truth table50%1/2
A
A= delete $params->{"addr"}
Aresult
11
00
490 8 }
491  
492 method options
493 1 ▶ {
Subroutine options: called CC=1 SCAR=0.0
494 return (
495 1 addr => $_addr,
496 );
497 8 }
498  
499 2 ▶ async method write ( $chip, $bytes )
Subroutine write: called CC=1 SCAR=0.0
500 2 {
501 2 await $chip->protocol->write( $bytes );
502 8 }
503  
504 1 ▶ async method read ( $chip, $len )
Subroutine read: called CC=1 SCAR=0.0
505 1 {
506 1 return await $chip->protocol->read( $len );
507 8 }
508 }
509  
510 8 class Device::Chip::NoritakeGU_D::_Iface::SPI {
511 1 ▶ method mountopts ( $ ) {}
Subroutine mountopts: called CC=1 SCAR=0.0
512  
513 method options
514 1 ▶ {
Subroutine options: called CC=1 SCAR=0.0
515 return (
516 1 mode => 0,
517 # max_bitrate => 2E6, # min clock period 500ns
518 # Need to slow the bitrate down in order to generate inter-word gaps
519 max_bitrate => 500E3,
520 );
521 8 }
522  
523 2 ▶ async method write ( $chip, $bytes )
Subroutine write: called CC=1 SCAR=0.0
524 2 {
525 2 await $chip->protocol->write( "\x44" . $bytes );
526 8 }
527  
528 1 ▶ async method read ( $chip, $len )
Subroutine read: called CC=1 SCAR=0.0
529 1 {
530 # TODO:
531 # The datasheet says that after you write a 0x58 byte, the very next byte
532 # you get back will be the status. Experimental testing shows you get an
533 # echo of the 0x58 first, then status.
534  
535 1 my $status = unpack "x C", await $chip->protocol->write_then_read( "\x58", 2 );
536  
537 # The datasheet says that after you write a 0x54 byte, you'll immediately
538 # get 0x00 then the data. Experimental testing suggests that you get an
539 # echo of the 0x54 byte first, then 0x00, then the data.
540  
541 1 my $bytes = await $chip->protocol->write_then_read( "\x54", ( $status & 0x1F ) + 2 );
542  
543 1 return substr $bytes, 2;
544 8 }
545 }
546  
547 8 =head1 AUTHOR
548  
549 Paul Evans <leonerd@leonerd.org.uk>
550  
551 =cut
552  
553 8 0x55AA;
↑ Summary