1. Introduction

This is an example of how to use the sw and matrix classes to react to key presses and releases from a multi-row, multi-column keypad.
It uses the reusable class matrixtest in the Classes/Tests directory to demonstrate the use of the OOSMOS publish/subscribe mechanism to deliver key events to a reusable object.

1.1 matrixtest Statechart

Figure 1. matrixtest Statechart

2. Matrix on Various Platforms

Because each platform could have unique pins or header layouts, we show how to setup matrix on multiple platforms.
The matrix test class acts as a simple keypad, reacting when a switch is pressed as well as when it's released.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
//	[MIT]
// OOSMOS matrixtest Class
//
// Copyright (c) 2014-2026 OOSMOS, LLC
// SPDX-License-Identifier: MIT
//

#ifndef matrixtest_h
#define matrixtest_h

#include "pin.h"

typedef struct matrixtestTag matrixtest;

extern matrixtest * matrixtestNew(pin * pRow1, pin * pRow2, pin * pRow3, pin * pCol1, pin * pCol2, pin * pCol3);

#endif

matrixtest.h - Portable Matrix Test Interface

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
//	[MIT]
// OOSMOS matrixtest Class
//
// Copyright (c) 2014-2026 OOSMOS, LLC
// SPDX-License-Identifier: MIT
//

#include "oosmos.h"
#include "pin.h"
#include "sw.h"
#include "prt.h"
#include "matrix.h"
#include "matrixtest.h"
#include <stdbool.h>
#include <stddef.h>

//>>>EVENTS
enum {
PressedEvent = 1,
ReleasedEvent = 2,
SpecialPressedEvent = 3,
SpecialReleasedEvent = 4
};

#ifdef oosmos_DEBUG
static const char * OOSMOS_EventNames(int EventCode)
{
switch (EventCode) {
case PressedEvent: return "PressedEvent";
case ReleasedEvent: return "ReleasedEvent";
case SpecialPressedEvent: return "SpecialPressedEvent";
case SpecialReleasedEvent: return "SpecialReleasedEvent";
default: return "";
}
}
#endif
//<<<EVENTS

typedef union {
oosmos_sEvent Base;
} uEvents;

struct matrixtestTag
{
//>>>DECL
oosmos_sStateMachine(ROOT, uEvents, 3);
oosmos_sLeaf State_State;
//<<<DECL

matrix * m_pMatrix;
};

static void NewSwitch(matrixtest * pMatrixTest, unsigned Row, unsigned Column, unsigned PressedEventCode, unsigned ReleasedEventCode, const char * pString)
{
matrix * pMatrix = pMatrixTest->m_pMatrix;

pin * pColumnPin = matrixGetColumnPin(pMatrix, Column);
sw * pSwitch = swNewDetached(pColumnPin);
matrixAssignSwitch(pMatrix, pSwitch, Row, Column);

swSubscribeCloseEvent(pSwitch, oosmos_EventQueue(pMatrixTest), PressedEventCode, (void *) pString);
swSubscribeOpenEvent(pSwitch, oosmos_EventQueue(pMatrixTest), ReleasedEventCode, (void *) pString);
}

static void Print(const char * pMessage, const oosmos_sEvent * pEvent)
{
const char * pString = (const char *) pEvent->m_pContext;
prtFormatted("%s %s\n", pMessage, pString);
}

//>>>CODE
static bool State_State_Code(void * pObject, oosmos_sState * pState, const oosmos_sEvent * pEvent)
{
switch (oosmos_EventCode(pEvent)) {
case PressedEvent: {
Print("Pressed", pEvent);
return true;
}
case ReleasedEvent: {
Print("Released", pEvent);
return true;
}
case SpecialPressedEvent: {
Print("Pressed special", pEvent);
return true;
}
case SpecialReleasedEvent: {
Print("Released special", pEvent);
return true;
}
}

oosmos_UNUSED(pObject);
oosmos_UNUSED(pState);
return false;
}
//<<<CODE

extern matrixtest * matrixtestNew(pin * pRow1, pin * pRow2, pin * pRow3, pin * pCol1, pin * pCol2, pin * pCol3)
{
oosmos_Allocate(pMatrixTest, matrixtest, 1, NULL);

//>>>INIT
oosmos_StateMachineInit(pMatrixTest, ROOT, NULL, State_State);
oosmos_LeafInit(pMatrixTest, State_State, ROOT, State_State_Code);

oosmos_Debug(pMatrixTest, OOSMOS_EventNames);
//<<<INIT

pMatrixTest -> m_pMatrix = matrixNew(3, 3, pRow1, pRow2, pRow3, pCol1, pCol2, pCol3);

NewSwitch(pMatrixTest, 1, 1, PressedEvent, ReleasedEvent, "1");
NewSwitch(pMatrixTest, 1, 2, PressedEvent, ReleasedEvent, "2");
NewSwitch(pMatrixTest, 1, 3, PressedEvent, ReleasedEvent, "3");

NewSwitch(pMatrixTest, 2, 1, SpecialPressedEvent, SpecialReleasedEvent, "4");
NewSwitch(pMatrixTest, 2, 2, PressedEvent, ReleasedEvent, "5");
NewSwitch(pMatrixTest, 2, 3, PressedEvent, ReleasedEvent, "6");

NewSwitch(pMatrixTest, 3, 1, PressedEvent, ReleasedEvent, "7");
NewSwitch(pMatrixTest, 3, 2, PressedEvent, ReleasedEvent, "8");
NewSwitch(pMatrixTest, 3, 3, PressedEvent, ReleasedEvent, "9");

return pMatrixTest;
}

matrixtest.c - Portable Matrix Test Implementation

2.1 Matrix on Arduino

The Arduino is a breeze to wire up. The pin assignments are printed on the Arduino circuit board and those are the numbers used to address them in the code.
Note that the red power jumper wire on the breadboard is not used. By convention, we wire each breadboard to connect the power rails to allow for intuitive part layouts.

Figure 2. Arduino Wiring Diagram

This is the main program for the Arduino.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
//	[MIT]
// OOSMOS - The Object-Oriented State Machine Operating System
//
// Copyright (c) 2014-2026 OOSMOS, LLC
// SPDX-License-Identifier: MIT
//

#include "oosmos.h"	#includes...
#include "pin.h"
#include "prt.h"
#include "matrix.h"
#include "matrixtest.h"

// Required by prt...
unsigned long prtArduinoBaudRate = 115200;

extern void setup()
{
pin * pRow1 = pinNew(7, pinOut, pinActiveLow);
pin * pRow2 = pinNew(6, pinOut, pinActiveLow);
pin * pRow3 = pinNew(5, pinOut, pinActiveLow);

pin * pCol1 = pinNew(4, pinIn, pinActiveLow);
pin * pCol2 = pinNew(3, pinIn, pinActiveLow);
pin * pCol3 = pinNew(2, pinIn, pinActiveLow);

matrixtestNew(pRow1, pRow2, pRow3, pCol1, pCol2, pCol3);
}

extern void loop()
{
oosmos_RunStateMachines();
}

MatrixExample.ino - Matrix main program for Arduino

2.2 Matrix on PIC32 Starter Kit

The PIC32 Starter Kit board is a very small board with virtually no breakout pins. To access the large number of pins on the PIC32 chip, Microchip sells an add-on expansion board onto which the starter kit board can be connected. The diagram below shows about half of the female expansion board connector J10.

Figure 3. PIC32 Wiring Diagram

This is the main program for the PIC32.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
//	[MIT]
// OOSMOS - PIC32 Matrix example main program
//
// Copyright (c) 2014-2026 OOSMOS, LLC
// SPDX-License-Identifier: MIT
//

#include "oosmos.h"	#includes...
#include "pin.h"
#include "matrixtest.h"

#pragma config FPLLMUL = MUL_20, FPLLIDIV = DIV_2, FPLLODIV = DIV_1, FWDTEN = OFF
#pragma config POSCMOD = HS, FNOSC = PRIPLL, FPBDIV = DIV_1

extern int main(void)
{
oosmos_ClockSpeedInMHz(80);

pin * pRow1 = pinNew(IOPORT_E, BIT_7, pinOut, pinActiveLow);
pin * pRow2 = pinNew(IOPORT_E, BIT_5, pinOut, pinActiveLow);
pin * pRow3 = pinNew(IOPORT_E, BIT_3, pinOut, pinActiveLow);

pin * pCol1 = pinNew(IOPORT_C, BIT_1, pinIn, pinActiveLow);
pin * pCol2 = pinNew(IOPORT_C, BIT_2, pinIn, pinActiveLow);
pin * pCol3 = pinNew(IOPORT_C, BIT_3, pinIn, pinActiveLow);

matrixtestNew(pRow1, pRow2, pRow3, pCol1, pCol2, pCol3);

for (;;) {
oosmos_RunStateMachines();
}
}

main.c - Matrix main program for PIC32