From 0a59a63fc5f4b6bcb50cdf97902c555b2d54e83d Mon Sep 17 00:00:00 2001 From: lonkaars Date: Thu, 11 May 2023 10:29:01 +0200 Subject: rename document and add required sections --- doc/dui.md | 100 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/dui.tex | 3 ++ doc/research.md | 94 --------------------------------------------------- doc/research.tex | 3 -- 4 files changed, 103 insertions(+), 97 deletions(-) create mode 100644 doc/dui.md create mode 100644 doc/dui.tex delete mode 100644 doc/research.md delete mode 100644 doc/research.tex diff --git a/doc/dui.md b/doc/dui.md new file mode 100644 index 0000000..ede73c8 --- /dev/null +++ b/doc/dui.md @@ -0,0 +1,100 @@ +# Introduction + +# Problem statement + +The following is the original project description (translated to English): + +> I would like to bring to market a vehicle that can drive independently from A +> to B. The vehicle must take into account traffic rules, road signs, traffic +> lights, etc. Research is being conducted using a small cart, the Pololu Zumo +> 32U4, on which a camera module Nicla Vision is mounted. The aim is to +> investigate the most appropriate method of recognizing the road, traffic +> signs and traffic lights. This should be demonstrated with a proof of +> concept. The cart does not need to drive fast, so the image processing does +> not need to be very fast. Assume one frame per second (or faster). + +# Specifications + +# Architecture + +# Research + +## Communication between the Nicla and Zumo + +In order to make the Zumo robot both detect where it is on a road, and steer to +keep driving on said road, some sort of communication needs to exist between +the Nicla and Zumo. As mentioned earlier\footnote{dit is nog niet benoemd}, all +machine vision-related tasks will happen on the Nicla board. Because the Nicla +board is the first to know how much to steer the cart, it makes sense to have +it control the cart by giving the Nicla a 'steering wheel' of sorts. + +This section tries to answer the question "What is the best protocol to use +over the existing UART connection between the Nicla and Zumo?". After a +brainstorm session, we came up with the following specifications for the +communication protocol: + +1. **Low bandwidth** + Less data means more responsive steering +2. **As simple as possible** + The Nicla only needs to control speed and steering +3. **Easy to mock and test** + The cart should be able to be controlled using a mock driver and the Nicla's + output should be testable (preferably using unit tests) +4. **Adaptive to noisy data** + The cart should gradually change speed and steering direction as to not slip + or cause excessive motion blur for the camera module on the Nicla +5. **Adaptive to Nicla failure** + If the Nicla crashes or can't detect anything, it will stop sending control + commands. In this case, the Zumo robot should slowly come to a halt. + +Where possible, it's generally benificial to re-use existing code to save on +time. Existing code exists for a custom binary protocol and a text-based +command protocol. Both of these were designed without bandwidth or latency in +mind, and mostly focus on robustness in the case of temporary disconnects or +noise on the communication lines, so a new protocol needs to be made. + +To address specification 1 and 2, the command length is fixed at 1 byte. This +means that UARTs built-in start/stop bit will take care of message start/end +detection, since most software interfaces for UART (including Arduino) string +multiple sequential messages together even if they're not part of the same UART +packet. + +To mock messages from the Nicla to the Zumo robot, a simple USB serial to UART +cable can be used, along with a small C or Python program to convert +keyboard/mouse input into steering/speed commands. A small software layer can +be implemented on the Nicla to log the semantic meaning of the commands instead +of sending actual UART data when run in a unit test. + +A PID controller can be used to smoothly interpolate between input +speed/steering values. This would also introduce some lag between when the +Nicla knows how much to steer, and when the Zumo actually steered the wanted +amount. Smoothing the speed/steering values does make it virtually impossible +for the Nicla to make it's own input data unusable because of motion blur, so +the lag needs to be handled in some other way as directly controlling speed +values without interpolation would lead to a garbage-in-garbage-out system. The +simplest solution to motion blur is limiting the maximum speed the Zumo robot +can drive at, which is the solution we're going to use as speed is not one of +the criteria of the complete system\footnote{Problem statement +(\ref{problem-statement})}. + +In the case the Nicla module crashes or fails to detect the road or roadsigns, +it will stop sending commands. If the Zumo robot would naively continue at it's +current speed, it could drive itself into nearby walls, shoes, pets, etc. To +make sure the robot doesn't get 'lost', it needs to slow down once it hasn't +received commands for some time. As mentioned in section \ref{TODO}, the Nicla +module is able to process at about 10 frames per second, so 2 seconds is a +reasonable time-out period. + +\def\communicationConclusion{ +The complete protocol will consist of single byte commands. A byte can either +change the cart speed or steering direction, both will apply gradually. When no +commands have been received for more than 2 seconds, the Zumo robot will +gradually slow down until it is stopped. Exact specifications of commands are +provided in the protocol specification document\footnote{dit document bestaat +nog niet}. +} +\communicationConclusion + +# Conclusion + +\communicationConclusion diff --git a/doc/dui.tex b/doc/dui.tex new file mode 100644 index 0000000..612ee40 --- /dev/null +++ b/doc/dui.tex @@ -0,0 +1,3 @@ +\newcommand\doctitle{DUI} +\input{base.tex} + diff --git a/doc/research.md b/doc/research.md deleted file mode 100644 index ba697a8..0000000 --- a/doc/research.md +++ /dev/null @@ -1,94 +0,0 @@ -# Problem statement - -The following is the original project description (translated to English): - -> I would like to bring to market a vehicle that can drive independently from A -> to B. The vehicle must take into account traffic rules, road signs, traffic -> lights, etc. Research is being conducted using a small cart, the Pololu Zumo -> 32U4, on which a camera module Nicla Vision is mounted. The aim is to -> investigate the most appropriate method of recognizing the road, traffic -> signs and traffic lights. This should be demonstrated with a proof of -> concept. The cart does not need to drive fast, so the image processing does -> not need to be very fast. Assume one frame per second (or faster). - -# TBD: The big question - -## Communication between the Nicla and Zumo - -In order to make the Zumo robot both detect where it is on a road, and steer to -keep driving on said road, some sort of communication needs to exist between -the Nicla and Zumo. As mentioned earlier\footnote{dit is nog niet benoemd}, all -machine vision-related tasks will happen on the Nicla board. Because the Nicla -board is the first to know how much to steer the cart, it makes sense to have -it control the cart by giving the Nicla a 'steering wheel' of sorts. - -This section tries to answer the question "What is the best protocol to use -over the existing UART connection between the Nicla and Zumo?". After a -brainstorm session, we came up with the following specifications for the -communication protocol: - -1. **Low bandwidth** - Less data means more responsive steering -2. **As simple as possible** - The Nicla only needs to control speed and steering -3. **Easy to mock and test** - The cart should be able to be controlled using a mock driver and the Nicla's - output should be testable (preferably using unit tests) -4. **Adaptive to noisy data** - The cart should gradually change speed and steering direction as to not slip - or cause excessive motion blur for the camera module on the Nicla -5. **Adaptive to Nicla failure** - If the Nicla crashes or can't detect anything, it will stop sending control - commands. In this case, the Zumo robot should slowly come to a halt. - -Where possible, it's generally benificial to re-use existing code to save on -time. Existing code exists for a custom binary protocol and a text-based -command protocol. Both of these were designed without bandwidth or latency in -mind, and mostly focus on robustness in the case of temporary disconnects or -noise on the communication lines, so a new protocol needs to be made. - -To address specification 1 and 2, the command length is fixed at 1 byte. This -means that UARTs built-in start/stop bit will take care of message start/end -detection, since most software interfaces for UART (including Arduino) string -multiple sequential messages together even if they're not part of the same UART -packet. - -To mock messages from the Nicla to the Zumo robot, a simple USB serial to UART -cable can be used, along with a small C or Python program to convert -keyboard/mouse input into steering/speed commands. A small software layer can -be implemented on the Nicla to log the semantic meaning of the commands instead -of sending actual UART data when run in a unit test. - -A PID controller can be used to smoothly interpolate between input -speed/steering values. This would also introduce some lag between when the -Nicla knows how much to steer, and when the Zumo actually steered the wanted -amount. Smoothing the speed/steering values does make it virtually impossible -for the Nicla to make it's own input data unusable because of motion blur, so -the lag needs to be handled in some other way as directly controlling speed -values without interpolation would lead to a garbage-in-garbage-out system. The -simplest solution to motion blur is limiting the maximum speed the Zumo robot -can drive at, which is the solution we're going to use as speed is not one of -the criteria of the complete system\footnote{Problem statement -(\ref{problem-statement})}. - -In the case the Nicla module crashes or fails to detect the road or roadsigns, -it will stop sending commands. If the Zumo robot would naively continue at it's -current speed, it could drive itself into nearby walls, shoes, pets, etc. To -make sure the robot doesn't get 'lost', it needs to slow down once it hasn't -received commands for some time. As mentioned in section \ref{TODO}, the Nicla -module is able to process at about 10 frames per second, so 2 seconds is a -reasonable time-out period. - -\def\communicationConclusion{ -The complete protocol will consist of single byte commands. A byte can either -change the cart speed or steering direction, both will apply gradually. When no -commands have been received for more than 2 seconds, the Zumo robot will -gradually slow down until it is stopped. Exact specifications of commands are -provided in the protocol specification document\footnote{dit document bestaat -nog niet}. -} -\communicationConclusion - -## Conclusion - -\communicationConclusion diff --git a/doc/research.tex b/doc/research.tex deleted file mode 100644 index af15484..0000000 --- a/doc/research.tex +++ /dev/null @@ -1,3 +0,0 @@ -\newcommand\doctitle{Research document} -\input{base.tex} - -- cgit v1.2.3