From 31fc78d0e00f9c82f03c88367a7e23b2df918ca6 Mon Sep 17 00:00:00 2001 From: jaseg Date: Fri, 5 Jan 2018 11:39:20 +0100 Subject: Add some documentation --- fw/README.rst | 20 ++++++++ fw/mac.c | 3 ++ fw/mac.h | 22 ++++++++ fw/main.c | 157 +++++++++++++++------------------------------------------ fw/test.py | 27 ++++++---- fw/transpose.c | 47 ++++++++++++++++- fw/transpose.h | 2 + 7 files changed, 149 insertions(+), 129 deletions(-) create mode 100644 fw/README.rst create mode 100644 fw/mac.c create mode 100644 fw/mac.h (limited to 'fw') diff --git a/fw/README.rst b/fw/README.rst new file mode 100644 index 0000000..1e81c46 --- /dev/null +++ b/fw/README.rst @@ -0,0 +1,20 @@ +Note on the LED modulation +========================== + +To control LED brightness, this project uses a modulation technique known as +"Binary Code Modulation" (BCM) or "Bit Angle Modulation" (BAM). The base idea is +to clock out all outputs in parallel bit-by-bit, then modulate this with a +precisely timed output enable signal. In contrast to PWM this allows almost +arbitrarily high channel counts and configurable modulation resolution at low +CPU overhead and high frame rates. In this project that is needed due to the +large number of channels (32) and the medium oversampling rate (1:8). + +A good article explaining BCM can be found on batsocks.co.uk_ and a nice video +explaining has been published by mikeselectricstuff_. A possible optimization +for even smoother brightness fading (probably mostly in unmultiplexed +applications) has been discussed in the forums at picbasic.co.uk_. + +.. _mikeselectricstuff: https://www.youtube.com/watch?v=Sq8SxVDO5wE +.. _`picbasic.co.uk`: http://www.picbasic.co.uk/forum/showthread.php?t=7393 +.. _batsocks.co.uk: http://www.batsocks.co.uk/readme/art_bcm_1.htm + diff --git a/fw/mac.c b/fw/mac.c new file mode 100644 index 0000000..4d05c9a --- /dev/null +++ b/fw/mac.c @@ -0,0 +1,3 @@ +#include "mac.h" + +uint32_t device_mac = 0xdeadbeef; diff --git a/fw/mac.h b/fw/mac.h new file mode 100644 index 0000000..26aaff6 --- /dev/null +++ b/fw/mac.h @@ -0,0 +1,22 @@ +#ifndef __MAC_H__ +#define __MAC_H__ + +#include + +/* Device MAC address. + * + * 32 bits might seem a little short for a device MAC, but at 20 bus nodes the probablility of a collision is about 1 in + * 10 million. Check for yourself using the python code below. + * + * #!/usr/bin/env python3 + * from operator import mul + * from functools import reduce + * m = 32 + * n = 20 + * print(reduce(mul, [2**m-i for i in range(n)]) / ((2**m)**n)) + * # -> 0.9999999557621786 + */ + +extern uint32_t device_mac; + +#endif /* __MAC_H__ */ diff --git a/fw/main.c b/fw/main.c index 50c9cfa..7740426 100644 --- a/fw/main.c +++ b/fw/main.c @@ -1,5 +1,4 @@ - - +/* Workaround for sub-par ST libraries */ #pragma GCC diagnostic push #pragma GCC diagnostic ignored "-Wstrict-aliasing" #include @@ -17,72 +16,9 @@ #include "transpose.h" #include "mac.h" -/* - * Part number: STM32F030F4C6 - */ - -typedef struct -{ - volatile uint32_t CTRL; /*!< Offset: 0x000 (R/W) Control Register */ - volatile uint32_t CYCCNT; /*!< Offset: 0x004 (R/W) Cycle Count Register */ - volatile uint32_t CPICNT; /*!< Offset: 0x008 (R/W) CPI Count Register */ - volatile uint32_t EXCCNT; /*!< Offset: 0x00C (R/W) Exception Overhead Count Register */ - volatile uint32_t SLEEPCNT; /*!< Offset: 0x010 (R/W) Sleep Count Register */ - volatile uint32_t LSUCNT; /*!< Offset: 0x014 (R/W) LSU Count Register */ - volatile uint32_t FOLDCNT; /*!< Offset: 0x018 (R/W) Folded-instruction Count Register */ - volatile uint32_t PCSR; /*!< Offset: 0x01C (R/ ) Program Counter Sample Register */ - volatile uint32_t COMP0; /*!< Offset: 0x020 (R/W) Comparator Register 0 */ - volatile uint32_t MASK0; /*!< Offset: 0x024 (R/W) Mask Register 0 */ - volatile uint32_t FUNCTION0; /*!< Offset: 0x028 (R/W) Function Register 0 */ - uint32_t RESERVED0[1]; - volatile uint32_t COMP1; /*!< Offset: 0x030 (R/W) Comparator Register 1 */ - volatile uint32_t MASK1; /*!< Offset: 0x034 (R/W) Mask Register 1 */ - volatile uint32_t FUNCTION1; /*!< Offset: 0x038 (R/W) Function Register 1 */ - uint32_t RESERVED1[1]; -} DWT_Type; - -#define DWT ((DWT_Type *)0xE0001000) -DWT_Type *dwt = DWT; - -void dwt0_configure(volatile void *addr) { - dwt->COMP0 = (uint32_t)addr; - dwt->MASK0 = 0; -} - -enum DWT_Function { - DWT_R = 5, - DWT_W = 6, - DWT_RW = 7 -}; - -void dwt0_enable(enum DWT_Function function) { - dwt->FUNCTION0 = function; -} - -/* Wait for about 0.2us */ -static void tick(void) { - /* 1 */ /* 2 */ /* 3 */ /* 4 */ /* 5 */ - /* 5 */ __asm__("nop"); __asm__("nop"); __asm__("nop"); __asm__("nop"); __asm__("nop"); - /* 10 */ __asm__("nop"); __asm__("nop"); __asm__("nop"); __asm__("nop"); __asm__("nop"); -} - -void spi_send(int data) { - SPI1->DR = data; - while (SPI1->SR & SPI_SR_BSY); -} - -void strobe_aux(void) { - GPIOA->BSRR = GPIO_BSRR_BS_10; - tick(); - GPIOA->BSRR = GPIO_BSRR_BR_10; -} - -void strobe_leds(void) { - GPIOA->BSRR = GPIO_BSRR_BS_9; - tick(); - GPIOA->BSRR = GPIO_BSRR_BR_9; -} +/* Microcontroller part number: STM32F030F4C6 */ +/* Things used for module status reporting. */ #define FIRMWARE_VERSION 2 #define HARDWARE_VERSION 4 @@ -97,6 +33,18 @@ volatile uint16_t adc_buf[2]; volatile unsigned int sys_time = 0; volatile unsigned int sys_time_seconds = 0; +/* Error counters for debugging */ +static unsigned int uart_overruns = 0; +static unsigned int frame_overruns = 0; +static unsigned int invalid_frames = 0; + +/* Status LED control */ +#define LED_STRETCHING_MS 50 +static volatile int error_led_timeout = 0; +static volatile int comm_led_timeout = 0; +static volatile int id_led_timeout = 0; + +/* Modulation data */ volatile struct framebuf fb[2] = {0}; volatile struct framebuf *read_fb=fb+0, *write_fb=fb+1; volatile int led_state = 0; @@ -108,45 +56,13 @@ volatile union { uint32_t mac_data; } rx_buf; +/* Auxiliary shift register values */ #define LED_COMM 0x0001 #define LED_ERROR 0x0002 #define LED_ID 0x0004 #define SR_ILED_HIGH 0x0080 #define SR_ILED_LOW 0x0040 -unsigned int stk_start(void) { - return SysTick->VAL; -} - -unsigned int stk_end(unsigned int start) { - return (start - SysTick->VAL) & 0xffffff; -} - -unsigned int stk_microseconds(void) { - return sys_time*1000 + (1000 - (SysTick->VAL / (SystemCoreClock/1000000))); -} - -void cfg_spi1() { - /* Configure SPI controller */ - SPI1->I2SCFGR = 0; - SPI1->CR2 &= ~SPI_CR2_DS_Msk; - SPI1->CR2 &= ~SPI_CR2_DS_Msk; - SPI1->CR2 |= LL_SPI_DATAWIDTH_16BIT; - - /* Baud rate PCLK/4 -> 12.5MHz */ - SPI1->CR1 = - SPI_CR1_BIDIMODE - | SPI_CR1_BIDIOE - | SPI_CR1_SSM - | SPI_CR1_SSI - | SPI_CR1_SPE - | (1<BSRR = GPIO_BSRR_BS_0; // Debug @@ -299,11 +216,6 @@ void TIM1_CC_IRQHandler() { if (active_segment == NSEGMENTS) { active_segment = 0; - /* FIXME remove this? - int time = stk_microseconds(); - frame_duration_us = time - last_frame_time; - last_frame_time = time; - */ /* Frame buffer swap */ if (fb_op == FB_UPDATE) { volatile struct framebuf *tmp = read_fb; @@ -319,6 +231,8 @@ void TIM1_CC_IRQHandler() { uint32_t aux_reg = (read_fb->brightness ? SR_ILED_HIGH : SR_ILED_LOW) | (led_state<<1); SPI1->DR = aux_reg | segment_map[active_segment]; + /* TODO: Measure frame rate for status report */ + /* Clear interrupt flag */ TIM1->SR &= ~TIM_SR_CC1IF_Msk; @@ -355,6 +269,27 @@ void TIM3_IRQHandler() { GPIOA->BSRR = GPIO_BSRR_BR_0; // Debug } +void cfg_spi1() { + /* Configure SPI controller */ + SPI1->I2SCFGR = 0; + SPI1->CR2 &= ~SPI_CR2_DS_Msk; + SPI1->CR2 &= ~SPI_CR2_DS_Msk; + SPI1->CR2 |= LL_SPI_DATAWIDTH_16BIT; + + /* Baud rate PCLK/4 -> 12.5MHz */ + SPI1->CR1 = + SPI_CR1_BIDIMODE + | SPI_CR1_BIDIOE + | SPI_CR1_SSM + | SPI_CR1_SSI + | SPI_CR1_SPE + | (1<CR1 = /* 8-bit -> M1, M0 clear */ /* RTOIE clear */ @@ -383,11 +318,6 @@ void uart_config(void) { NVIC_SetPriority(USART1_IRQn, 1); } -#define LED_STRETCHING_MS 50 -static volatile int error_led_timeout = 0; -static volatile int comm_led_timeout = 0; -static volatile int id_led_timeout = 0; - void trigger_error_led() { error_led_timeout = LED_STRETCHING_MS; } @@ -400,11 +330,6 @@ void trigger_id_led() { id_led_timeout = LED_STRETCHING_MS; } -/* Error counters for debugging */ -static unsigned int uart_overruns = 0; -static unsigned int frame_overruns = 0; -static unsigned int invalid_frames = 0; - void tx_char(uint8_t c) { while (!(USART1->ISR & USART_ISR_TC)); USART1->TDR = c; @@ -761,7 +686,7 @@ int main(void) { /* Clear frame buffer */ read_fb->brightness = 1; for (int i=0; idata)/sizeof(uint32_t); i++) { - read_fb->data[i] = 0xffffffff; /* FIXME DEBUG 0x00000000; */ + read_fb->data[i] = 0xffffffff; /* FIXME this is a debug value. Should be 0x00000000; */ } cfg_timers_led(); diff --git a/fw/test.py b/fw/test.py index 695d9d5..63cb324 100755 --- a/fw/test.py +++ b/fw/test.py @@ -62,6 +62,7 @@ def send_framebuffer(ser, mac, frame): def discover_macs(ser, count=20): found_macs = [] while True: + ser.flushInput() ser.write(b'\0') frame = receive_frame(ser) if len(frame) == 4: @@ -77,6 +78,8 @@ def discover_macs(ser, count=20): def parse_status_frame(frame): print('frame len:', len(frame)) + if not frame: + return None ( firmware_version, hardware_version, digit_rows, @@ -112,24 +115,26 @@ if __name__ == '__main__': frame_len = 4*8*8 black, red = [0]*frame_len, [255]*frame_len frames = \ - [black]*10 +\ - [red]*10 +\ - [[i]*frame_len for i in range(256)] +\ - [[(i + (d//8)*8) % 256*8 for d in range(frame_len)] for i in range(256)] + [black] + #[[0]*i + [255]*(256-i) for i in range(257)] + #[[(i + d)%256 for d in range(frame_len)] for i in range(256)] + #[black]*10 +\ + #[red]*10 +\ + #[[i]*frame_len for i in range(256)] +\ + #[[(i + (d//8)*8) % 256*8 for d in range(frame_len)] for i in range(256)] #frames = [red, black]*5 #frames = [ x for l in [[([0]*i+[255]+[0]*(7-i))*32]*2 for i in range(8)] for x in l ] - found_macs = discover_macs(ser, 1) + found_macs = [0xdeadbeef] #discover_macs(ser, 1) mac, = found_macs import pprint while True: - pprint.pprint(fetch_status(ser, mac)) - time.sleep(0.02) - - while True: + try: + pprint.pprint(fetch_status(ser, mac)) + except e: + print(e) for i, frame in enumerate(frames): send_framebuffer(ser, mac, frame) - print('sending', i, len(frame)) - time.sleep(0.02) + time.sleep(0.1) # to produce framing errors: ser.write(b'\02a\0') diff --git a/fw/transpose.c b/fw/transpose.c index a6c7e71..7af3e8e 100644 --- a/fw/transpose.c +++ b/fw/transpose.c @@ -4,14 +4,52 @@ #include "transpose.h" +/* This file contains conversion routines that pre-format the brightness data + * received from the UART such that the interrupt service routines only need to + * push it out the SPI without further computation, making these ISRs nice and + * tight. + * + * To understand this code note the multiplexing scheme used on the board. The + * circuit contains two MBI5026 shift-register LED drivers of 16 channels each + * cascaded. Effectively this behaves like a 32-channel LED driver fed data + * serially. Each output is connected to a single digit's COM pin. All digit's + * segment anode pins are connected together in a large bus fed by one of the + * two auxiliary shift registers. + * + * The firmware is selecting each segment in turn with a full BCM cycle for each + * segment before the next one is selected. + */ + +/* This array maps the 32 adressable digits on a board to the 32 bits shifted + * out to the LED drivers. */ uint8_t digit_map[33] = { 0, 1, 2, 3, 28,29,30,31, 4, 5, 6, 7, 24,25,26,27, 8, 9,10,11, 20,21,22,23, 12,13,14,15, 16,17,18,19 }; -void transpose_data(volatile uint8_t *rx_buf, volatile struct framebuf *out_fb) { + +/* This function produces a 10-bit output buffer ready for the modulation ISRs + * from 10-bit input data encoded for the UART. For the precise data format, see + * transpose.h. + * + * On the UART side we have digits in the order defined in digit_map, 10 byte + * per digit. The first 8 bytes are the 8 LSBs of each segments brightness value + * in the order [A, B, C, D, E, F, G, DECIMAL_POINT]. The two MSBs to make each + * value 10-bit are bit-packed into the remaining two bytes in big-endian byte + * order starting from DP. + * + * On the display frame buffer side, data is stored in multiplexing order: + * first digits, then time/bits and finally segments. So for each segment you + * have a large buffer containing all the bit periods and digits, and for each + * bit period you have 32 bits for all 32 digits. + */ +void transpose_data(volatile uint8_t *rx_buf, volatile struct framebuf *out_fb) +{ + /* FIXME this can probably be removed. */ memset((uint8_t *)out_fb, 0, sizeof(*out_fb)); + + /* 8 MSB loop */ struct data_format *rxp = (struct data_format *)rx_buf; for (int bit=0; bit<8; bit++) { /* bits */ uint32_t bit_mask = 1U<frame[bit].data; for (int seg=0; seg<8; seg++) { /* segments */ @@ -40,10 +80,13 @@ void transpose_data(volatile uint8_t *rx_buf, volatile struct framebuf *out_fb) frame_data[seg] = acc; } } + + /* Global analog brightness value */ out_fb->brightness = ((volatile struct framebuf *)rx_buf)->brightness; } - +/* This function was used for testing transpose_data. It does precisely the + * reverse operation. */ void untranspose_data(struct framebuf *fb, uint8_t *txbuf) { memset(txbuf, 0, sizeof(*fb)); diff --git a/fw/transpose.h b/fw/transpose.h index 389071c..467b12d 100644 --- a/fw/transpose.h +++ b/fw/transpose.h @@ -15,6 +15,7 @@ enum { FRAME_SIZE_WORDS = NROWS*NCOLS*NSEGMENTS/32, }; +/* Framebuffer data format pre-formatted for BCM ISRs */ struct framebuf { /* Multiplexing order: first Digits, then Time/bits, last Segments */ union { @@ -28,6 +29,7 @@ struct framebuf { uint8_t brightness; /* 0 or 1; controls global brighntess control */ }; +/* Efficiently-packed UART data format */ struct data_format { union { uint8_t high[8]; -- cgit