diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 00000000..c199d902 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,60 @@ +name: ci +on: + push: + branches: + - main + +env: + PYTHON_VERSION: 3.x + +jobs: + deploy: + name: Build documentation + runs-on: ubuntu-latest + steps: + + # - name: Install Ubuntu Dependencies for Material for MkDocs Insiders + # run: | + # sudo apt-get install \ + # libcairo2-dev \ + # libfreetype6-dev \ + # libffi-dev \ + # libjpeg-dev \ + # libpng-dev \ + # libz-dev + + - name: Checkout Repository + uses: actions/checkout@v3 + with: + fetch-depth: 0 + + - name: Setup Python runtime + uses: actions/setup-python@v3 + with: + python-version: ${{ env.PYTHON_VERSION }} + + - name: Install Python Dependencies + run: | + pip install \ + mkdocs \ + mkdocs-material \ + mkdocs-minify-plugin \ + mkdocs-redirects \ + mkdocs-video \ + mkdocs-git-revision-date-localized-plugin \ + mkdocs-rss-plugin + + # For mkdocs insiders build purposes to use later + # Pillow \ + # cairosvg \ + + # - name: Install mkdocs-material-insiders + # env: + # GH_TOKEN: ${{ secrets.MKDOCS_MATERIAL_INSIDERS }} + # run: | + # pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git + + - name: Deploy Documentation + run: | + mkdocs gh-deploy --force + mkdocs --version diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..f9fa9bbe --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,25 @@ +# MiSTer FPGA MkDocs contribution info +Try your best to follow along with the general structure of folders (categories) and the quality of the articles. Remember, quality over quantity. :) + +It's very easy to contribute, just fork this repo, make your changes (such as making a new markdown file or editing one) and follow normal markdown syntax, commit changes to your fork, submit your pull request, and we will review it to see if it's suitable to merge. + +https://MiSTer-devel.github.io/MkDocs_MiSTer/editing/ + +## Style guide +Any internally facing links must be relative links. `./docs` is the implicit root folder, so if you want to link to the assets folder you just need to use `/assets/` and type in the file that you want to link to in there. + +Any externally facing links need to use "open link in new tab" by default, so as not to confuse the user and keep them on their setup step, reduce the need to click "back", etc... This is enabled by the `- attr_list` extension. To do this, just add `{target=_blank}` to the end of your link. e.g.: + +`[DE10-Nano](http://de10-nano.terasic.com){target=_blank}` + +Make images links when it may benefit the user. Here is the syntax: + +`[![Download Mr. Fusion](dl-mr-fusion.png)](https://github.com/MiSTer-devel/mr-fusion/releases){target=_blank}` + +To embed a video: + +`![type:video](videos/downloader.mp4)` + +To link to another doc with a specific sub-url: + +`[WiFi tutorial](wifi.md#setup-wifi-with-a-script)` diff --git a/LICENSE b/LICENSE new file mode 100644 index 00000000..ba3ba9ae --- /dev/null +++ b/LICENSE @@ -0,0 +1,769 @@ +MIT License + +Copyright (c) 2022 Kevin Coleman & MiSTer FPGA + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +-------------------------------- +License for HeWhoIsRed's Artwork +-------------------------------- + +This license is for the MiSTer-Kun, the MiSTerFPGA logo, the favicon, and any other original artwork made by HeWhoIsRed. + +Red gave us permission to use the art and said it's free to use. :) + +-------------------------------- +LICENSE from Material for MkDocs +-------------------------------- + +MIT License + +Copyright (c) 2016-2021 Martin Donath + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +------------------- +License from MkDocs +------------------- + +Included projects + +Themes used under license from the ReadTheDocs projects. + + ReadTheDocs theme - View license. + +Many thanks to the authors and contributors of those wonderful projects. +MkDocs License (BSD) + +Copyright © 2014, Tom Christie. All rights reserved. + +Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: + +Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + +----------------------------------------- +License from readthedocs sphinx_rtd_theme +----------------------------------------- + +The MIT License (MIT) + +Copyright (c) 2013-2018 Dave Snider, Read the Docs, Inc. & contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the "Software"), to deal in +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software is furnished to do so, +subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS +FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR +COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER +IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN +CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +------------------------------ +License for mkdocs-rss-plugin +------------------------------ + + GNU GENERAL PUBLIC LICENSE + Version 3, 29 June 2007 + + Copyright (C) 2007 Free Software Foundation, Inc. + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The GNU General Public License is a free, copyleft license for +software and other kinds of works. + + The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +the GNU General Public License is intended to guarantee your freedom to +share and change all versions of a program--to make sure it remains free +software for all its users. We, the Free Software Foundation, use the +GNU General Public License for most of our software; it applies also to +any other work released this way by its authors. You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +them if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs, and that you know you can do these things. + + To protect your rights, we need to prevent others from denying you +these rights or asking you to surrender the rights. Therefore, you have +certain responsibilities if you distribute copies of the software, or if +you modify it: responsibilities to respect the freedom of others. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must pass on to the recipients the same +freedoms that you received. You must make sure that they, too, receive +or can get the source code. And you must show them these terms so they +know their rights. + + Developers that use the GNU GPL protect your rights with two steps: +(1) assert copyright on the software, and (2) offer you this License +giving you legal permission to copy, distribute and/or modify it. + + For the developers' and authors' protection, the GPL clearly explains +that there is no warranty for this free software. For both users' and +authors' sake, the GPL requires that modified versions be marked as +changed, so that their problems will not be attributed erroneously to +authors of previous versions. + + Some devices are designed to deny users access to install or run +modified versions of the software inside them, although the manufacturer +can do so. This is fundamentally incompatible with the aim of +protecting users' freedom to change the software. The systematic +pattern of such abuse occurs in the area of products for individuals to +use, which is precisely where it is most unacceptable. Therefore, we +have designed this version of the GPL to prohibit the practice for those +products. If such problems arise substantially in other domains, we +stand ready to extend this provision to those domains in future versions +of the GPL, as needed to protect the freedom of users. + + Finally, every program is threatened constantly by software patents. +States should not allow patents to restrict development and use of +software on general-purpose computers, but in those that do, we wish to +avoid the special danger that patents applied to a free program could +make it effectively proprietary. To prevent this, the GPL assures that +patents cannot be used to render the program non-free. + + The precise terms and conditions for copying, distribution and +modification follow. + + TERMS AND CONDITIONS + + 0. Definitions. + + "This License" refers to version 3 of the GNU General Public License. + + "Copyright" also means copyright-like laws that apply to other kinds of +works, such as semiconductor masks. + + "The Program" refers to any copyrightable work licensed under this +License. Each licensee is addressed as "you". "Licensees" and +"recipients" may be individuals or organizations. + + To "modify" a work means to copy from or adapt all or part of the work +in a fashion requiring copyright permission, other than the making of an +exact copy. The resulting work is called a "modified version" of the +earlier work or a work "based on" the earlier work. + + A "covered work" means either the unmodified Program or a work based +on the Program. + + To "propagate" a work means to do anything with it that, without +permission, would make you directly or secondarily liable for +infringement under applicable copyright law, except executing it on a +computer or modifying a private copy. Propagation includes copying, +distribution (with or without modification), making available to the +public, and in some countries other activities as well. + + To "convey" a work means any kind of propagation that enables other +parties to make or receive copies. Mere interaction with a user through +a computer network, with no transfer of a copy, is not conveying. + + An interactive user interface displays "Appropriate Legal Notices" +to the extent that it includes a convenient and prominently visible +feature that (1) displays an appropriate copyright notice, and (2) +tells the user that there is no warranty for the work (except to the +extent that warranties are provided), that licensees may convey the +work under this License, and how to view a copy of this License. If +the interface presents a list of user commands or options, such as a +menu, a prominent item in the list meets this criterion. + + 1. Source Code. + + The "source code" for a work means the preferred form of the work +for making modifications to it. "Object code" means any non-source +form of a work. + + A "Standard Interface" means an interface that either is an official +standard defined by a recognized standards body, or, in the case of +interfaces specified for a particular programming language, one that +is widely used among developers working in that language. + + The "System Libraries" of an executable work include anything, other +than the work as a whole, that (a) is included in the normal form of +packaging a Major Component, but which is not part of that Major +Component, and (b) serves only to enable use of the work with that +Major Component, or to implement a Standard Interface for which an +implementation is available to the public in source code form. A +"Major Component", in this context, means a major essential component +(kernel, window system, and so on) of the specific operating system +(if any) on which the executable work runs, or a compiler used to +produce the work, or an object code interpreter used to run it. + + The "Corresponding Source" for a work in object code form means all +the source code needed to generate, install, and (for an executable +work) run the object code and to modify the work, including scripts to +control those activities. However, it does not include the work's +System Libraries, or general-purpose tools or generally available free +programs which are used unmodified in performing those activities but +which are not part of the work. For example, Corresponding Source +includes interface definition files associated with source files for +the work, and the source code for shared libraries and dynamically +linked subprograms that the work is specifically designed to require, +such as by intimate data communication or control flow between those +subprograms and other parts of the work. + + The Corresponding Source need not include anything that users +can regenerate automatically from other parts of the Corresponding +Source. + + The Corresponding Source for a work in source code form is that +same work. + + 2. Basic Permissions. + + All rights granted under this License are granted for the term of +copyright on the Program, and are irrevocable provided the stated +conditions are met. This License explicitly affirms your unlimited +permission to run the unmodified Program. The output from running a +covered work is covered by this License only if the output, given its +content, constitutes a covered work. This License acknowledges your +rights of fair use or other equivalent, as provided by copyright law. + + You may make, run and propagate covered works that you do not +convey, without conditions so long as your license otherwise remains +in force. You may convey covered works to others for the sole purpose +of having them make modifications exclusively for you, or provide you +with facilities for running those works, provided that you comply with +the terms of this License in conveying all material for which you do +not control copyright. Those thus making or running the covered works +for you must do so exclusively on your behalf, under your direction +and control, on terms that prohibit them from making any copies of +your copyrighted material outside their relationship with you. + + Conveying under any other circumstances is permitted solely under +the conditions stated below. Sublicensing is not allowed; section 10 +makes it unnecessary. + + 3. Protecting Users' Legal Rights From Anti-Circumvention Law. + + No covered work shall be deemed part of an effective technological +measure under any applicable law fulfilling obligations under article +11 of the WIPO copyright treaty adopted on 20 December 1996, or +similar laws prohibiting or restricting circumvention of such +measures. + + When you convey a covered work, you waive any legal power to forbid +circumvention of technological measures to the extent such circumvention +is effected by exercising rights under this License with respect to +the covered work, and you disclaim any intention to limit operation or +modification of the work as a means of enforcing, against the work's +users, your or third parties' legal rights to forbid circumvention of +technological measures. + + 4. Conveying Verbatim Copies. + + You may convey verbatim copies of the Program's source code as you +receive it, in any medium, provided that you conspicuously and +appropriately publish on each copy an appropriate copyright notice; +keep intact all notices stating that this License and any +non-permissive terms added in accord with section 7 apply to the code; +keep intact all notices of the absence of any warranty; and give all +recipients a copy of this License along with the Program. + + You may charge any price or no price for each copy that you convey, +and you may offer support or warranty protection for a fee. + + 5. Conveying Modified Source Versions. + + You may convey a work based on the Program, or the modifications to +produce it from the Program, in the form of source code under the +terms of section 4, provided that you also meet all of these conditions: + + a) The work must carry prominent notices stating that you modified + it, and giving a relevant date. + + b) The work must carry prominent notices stating that it is + released under this License and any conditions added under section + 7. This requirement modifies the requirement in section 4 to + "keep intact all notices". + + c) You must license the entire work, as a whole, under this + License to anyone who comes into possession of a copy. This + License will therefore apply, along with any applicable section 7 + additional terms, to the whole of the work, and all its parts, + regardless of how they are packaged. This License gives no + permission to license the work in any other way, but it does not + invalidate such permission if you have separately received it. + + d) If the work has interactive user interfaces, each must display + Appropriate Legal Notices; however, if the Program has interactive + interfaces that do not display Appropriate Legal Notices, your + work need not make them do so. + + A compilation of a covered work with other separate and independent +works, which are not by their nature extensions of the covered work, +and which are not combined with it such as to form a larger program, +in or on a volume of a storage or distribution medium, is called an +"aggregate" if the compilation and its resulting copyright are not +used to limit the access or legal rights of the compilation's users +beyond what the individual works permit. Inclusion of a covered work +in an aggregate does not cause this License to apply to the other +parts of the aggregate. + + 6. Conveying Non-Source Forms. + + You may convey a covered work in object code form under the terms +of sections 4 and 5, provided that you also convey the +machine-readable Corresponding Source under the terms of this License, +in one of these ways: + + a) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by the + Corresponding Source fixed on a durable physical medium + customarily used for software interchange. + + b) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by a + written offer, valid for at least three years and valid for as + long as you offer spare parts or customer support for that product + model, to give anyone who possesses the object code either (1) a + copy of the Corresponding Source for all the software in the + product that is covered by this License, on a durable physical + medium customarily used for software interchange, for a price no + more than your reasonable cost of physically performing this + conveying of source, or (2) access to copy the + Corresponding Source from a network server at no charge. + + c) Convey individual copies of the object code with a copy of the + written offer to provide the Corresponding Source. This + alternative is allowed only occasionally and noncommercially, and + only if you received the object code with such an offer, in accord + with subsection 6b. + + d) Convey the object code by offering access from a designated + place (gratis or for a charge), and offer equivalent access to the + Corresponding Source in the same way through the same place at no + further charge. You need not require recipients to copy the + Corresponding Source along with the object code. If the place to + copy the object code is a network server, the Corresponding Source + may be on a different server (operated by you or a third party) + that supports equivalent copying facilities, provided you maintain + clear directions next to the object code saying where to find the + Corresponding Source. Regardless of what server hosts the + Corresponding Source, you remain obligated to ensure that it is + available for as long as needed to satisfy these requirements. + + e) Convey the object code using peer-to-peer transmission, provided + you inform other peers where the object code and Corresponding + Source of the work are being offered to the general public at no + charge under subsection 6d. + + A separable portion of the object code, whose source code is excluded +from the Corresponding Source as a System Library, need not be +included in conveying the object code work. + + A "User Product" is either (1) a "consumer product", which means any +tangible personal property which is normally used for personal, family, +or household purposes, or (2) anything designed or sold for incorporation +into a dwelling. In determining whether a product is a consumer product, +doubtful cases shall be resolved in favor of coverage. For a particular +product received by a particular user, "normally used" refers to a +typical or common use of that class of product, regardless of the status +of the particular user or of the way in which the particular user +actually uses, or expects or is expected to use, the product. A product +is a consumer product regardless of whether the product has substantial +commercial, industrial or non-consumer uses, unless such uses represent +the only significant mode of use of the product. + + "Installation Information" for a User Product means any methods, +procedures, authorization keys, or other information required to install +and execute modified versions of a covered work in that User Product from +a modified version of its Corresponding Source. The information must +suffice to ensure that the continued functioning of the modified object +code is in no case prevented or interfered with solely because +modification has been made. + + If you convey an object code work under this section in, or with, or +specifically for use in, a User Product, and the conveying occurs as +part of a transaction in which the right of possession and use of the +User Product is transferred to the recipient in perpetuity or for a +fixed term (regardless of how the transaction is characterized), the +Corresponding Source conveyed under this section must be accompanied +by the Installation Information. But this requirement does not apply +if neither you nor any third party retains the ability to install +modified object code on the User Product (for example, the work has +been installed in ROM). + + The requirement to provide Installation Information does not include a +requirement to continue to provide support service, warranty, or updates +for a work that has been modified or installed by the recipient, or for +the User Product in which it has been modified or installed. Access to a +network may be denied when the modification itself materially and +adversely affects the operation of the network or violates the rules and +protocols for communication across the network. + + Corresponding Source conveyed, and Installation Information provided, +in accord with this section must be in a format that is publicly +documented (and with an implementation available to the public in +source code form), and must require no special password or key for +unpacking, reading or copying. + + 7. Additional Terms. + + "Additional permissions" are terms that supplement the terms of this +License by making exceptions from one or more of its conditions. +Additional permissions that are applicable to the entire Program shall +be treated as though they were included in this License, to the extent +that they are valid under applicable law. If additional permissions +apply only to part of the Program, that part may be used separately +under those permissions, but the entire Program remains governed by +this License without regard to the additional permissions. + + When you convey a copy of a covered work, you may at your option +remove any additional permissions from that copy, or from any part of +it. (Additional permissions may be written to require their own +removal in certain cases when you modify the work.) You may place +additional permissions on material, added by you to a covered work, +for which you have or can give appropriate copyright permission. + + Notwithstanding any other provision of this License, for material you +add to a covered work, you may (if authorized by the copyright holders of +that material) supplement the terms of this License with terms: + + a) Disclaiming warranty or limiting liability differently from the + terms of sections 15 and 16 of this License; or + + b) Requiring preservation of specified reasonable legal notices or + author attributions in that material or in the Appropriate Legal + Notices displayed by works containing it; or + + c) Prohibiting misrepresentation of the origin of that material, or + requiring that modified versions of such material be marked in + reasonable ways as different from the original version; or + + d) Limiting the use for publicity purposes of names of licensors or + authors of the material; or + + e) Declining to grant rights under trademark law for use of some + trade names, trademarks, or service marks; or + + f) Requiring indemnification of licensors and authors of that + material by anyone who conveys the material (or modified versions of + it) with contractual assumptions of liability to the recipient, for + any liability that these contractual assumptions directly impose on + those licensors and authors. + + All other non-permissive additional terms are considered "further +restrictions" within the meaning of section 10. If the Program as you +received it, or any part of it, contains a notice stating that it is +governed by this License along with a term that is a further +restriction, you may remove that term. If a license document contains +a further restriction but permits relicensing or conveying under this +License, you may add to a covered work material governed by the terms +of that license document, provided that the further restriction does +not survive such relicensing or conveying. + + If you add terms to a covered work in accord with this section, you +must place, in the relevant source files, a statement of the +additional terms that apply to those files, or a notice indicating +where to find the applicable terms. + + Additional terms, permissive or non-permissive, may be stated in the +form of a separately written license, or stated as exceptions; +the above requirements apply either way. + + 8. Termination. + + You may not propagate or modify a covered work except as expressly +provided under this License. Any attempt otherwise to propagate or +modify it is void, and will automatically terminate your rights under +this License (including any patent licenses granted under the third +paragraph of section 11). + + However, if you cease all violation of this License, then your +license from a particular copyright holder is reinstated (a) +provisionally, unless and until the copyright holder explicitly and +finally terminates your license, and (b) permanently, if the copyright +holder fails to notify you of the violation by some reasonable means +prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + + Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, you do not qualify to receive new licenses for the same +material under section 10. + + 9. Acceptance Not Required for Having Copies. + + You are not required to accept this License in order to receive or +run a copy of the Program. Ancillary propagation of a covered work +occurring solely as a consequence of using peer-to-peer transmission +to receive a copy likewise does not require acceptance. However, +nothing other than this License grants you permission to propagate or +modify any covered work. These actions infringe copyright if you do +not accept this License. Therefore, by modifying or propagating a +covered work, you indicate your acceptance of this License to do so. + + 10. Automatic Licensing of Downstream Recipients. + + Each time you convey a covered work, the recipient automatically +receives a license from the original licensors, to run, modify and +propagate that work, subject to this License. You are not responsible +for enforcing compliance by third parties with this License. + + An "entity transaction" is a transaction transferring control of an +organization, or substantially all assets of one, or subdividing an +organization, or merging organizations. If propagation of a covered +work results from an entity transaction, each party to that +transaction who receives a copy of the work also receives whatever +licenses to the work the party's predecessor in interest had or could +give under the previous paragraph, plus a right to possession of the +Corresponding Source of the work from the predecessor in interest, if +the predecessor has it or can get it with reasonable efforts. + + You may not impose any further restrictions on the exercise of the +rights granted or affirmed under this License. For example, you may +not impose a license fee, royalty, or other charge for exercise of +rights granted under this License, and you may not initiate litigation +(including a cross-claim or counterclaim in a lawsuit) alleging that +any patent claim is infringed by making, using, selling, offering for +sale, or importing the Program or any portion of it. + + 11. Patents. + + A "contributor" is a copyright holder who authorizes use under this +License of the Program or a work on which the Program is based. The +work thus licensed is called the contributor's "contributor version". + + A contributor's "essential patent claims" are all patent claims +owned or controlled by the contributor, whether already acquired or +hereafter acquired, that would be infringed by some manner, permitted +by this License, of making, using, or selling its contributor version, +but do not include claims that would be infringed only as a +consequence of further modification of the contributor version. For +purposes of this definition, "control" includes the right to grant +patent sublicenses in a manner consistent with the requirements of +this License. + + Each contributor grants you a non-exclusive, worldwide, royalty-free +patent license under the contributor's essential patent claims, to +make, use, sell, offer for sale, import and otherwise run, modify and +propagate the contents of its contributor version. + + In the following three paragraphs, a "patent license" is any express +agreement or commitment, however denominated, not to enforce a patent +(such as an express permission to practice a patent or covenant not to +sue for patent infringement). To "grant" such a patent license to a +party means to make such an agreement or commitment not to enforce a +patent against the party. + + If you convey a covered work, knowingly relying on a patent license, +and the Corresponding Source of the work is not available for anyone +to copy, free of charge and under the terms of this License, through a +publicly available network server or other readily accessible means, +then you must either (1) cause the Corresponding Source to be so +available, or (2) arrange to deprive yourself of the benefit of the +patent license for this particular work, or (3) arrange, in a manner +consistent with the requirements of this License, to extend the patent +license to downstream recipients. "Knowingly relying" means you have +actual knowledge that, but for the patent license, your conveying the +covered work in a country, or your recipient's use of the covered work +in a country, would infringe one or more identifiable patents in that +country that you have reason to believe are valid. + + If, pursuant to or in connection with a single transaction or +arrangement, you convey, or propagate by procuring conveyance of, a +covered work, and grant a patent license to some of the parties +receiving the covered work authorizing them to use, propagate, modify +or convey a specific copy of the covered work, then the patent license +you grant is automatically extended to all recipients of the covered +work and works based on it. + + A patent license is "discriminatory" if it does not include within +the scope of its coverage, prohibits the exercise of, or is +conditioned on the non-exercise of one or more of the rights that are +specifically granted under this License. You may not convey a covered +work if you are a party to an arrangement with a third party that is +in the business of distributing software, under which you make payment +to the third party based on the extent of your activity of conveying +the work, and under which the third party grants, to any of the +parties who would receive the covered work from you, a discriminatory +patent license (a) in connection with copies of the covered work +conveyed by you (or copies made from those copies), or (b) primarily +for and in connection with specific products or compilations that +contain the covered work, unless you entered into that arrangement, +or that patent license was granted, prior to 28 March 2007. + + Nothing in this License shall be construed as excluding or limiting +any implied license or other defenses to infringement that may +otherwise be available to you under applicable patent law. + + 12. No Surrender of Others' Freedom. + + If conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot convey a +covered work so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you may +not convey it at all. For example, if you agree to terms that obligate you +to collect a royalty for further conveying from those to whom you convey +the Program, the only way you could satisfy both those terms and this +License would be to refrain entirely from conveying the Program. + + 13. Use with the GNU Affero General Public License. + + Notwithstanding any other provision of this License, you have +permission to link or combine any covered work with a work licensed +under version 3 of the GNU Affero General Public License into a single +combined work, and to convey the resulting work. The terms of this +License will continue to apply to the part which is the covered work, +but the special requirements of the GNU Affero General Public License, +section 13, concerning interaction through a network will apply to the +combination as such. + + 14. Revised Versions of this License. + + The Free Software Foundation may publish revised and/or new versions of +the GNU General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + + Each version is given a distinguishing version number. If the +Program specifies that a certain numbered version of the GNU General +Public License "or any later version" applies to it, you have the +option of following the terms and conditions either of that numbered +version or of any later version published by the Free Software +Foundation. If the Program does not specify a version number of the +GNU General Public License, you may choose any version ever published +by the Free Software Foundation. + + If the Program specifies that a proxy can decide which future +versions of the GNU General Public License can be used, that proxy's +public statement of acceptance of a version permanently authorizes you +to choose that version for the Program. + + Later license versions may give you additional or different +permissions. However, no additional obligations are imposed on any +author or copyright holder as a result of your choosing to follow a +later version. + + 15. Disclaimer of Warranty. + + THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY +APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT +HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY +OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, +THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM +IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF +ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + + 16. Limitation of Liability. + + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS +THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY +GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE +USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF +DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD +PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), +EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF +SUCH DAMAGES. + + 17. Interpretation of Sections 15 and 16. + + If the disclaimer of warranty and limitation of liability provided +above cannot be given local legal effect according to their terms, +reviewing courts shall apply local law that most closely approximates +an absolute waiver of all civil liability in connection with the +Program, unless a warranty or assumption of liability accompanies a +copy of the Program in return for a fee. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +state the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . + +Also add information on how to contact you by electronic and paper mail. + + If the program does terminal interaction, make it output a short +notice like this when it starts in an interactive mode: + + Copyright (C) + This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, your program's commands +might be different; for a GUI interface, you would use an "about box". + + You should also get your employer (if you work as a programmer) or school, +if any, to sign a "copyright disclaimer" for the program, if necessary. +For more information on this, and how to apply and follow the GNU GPL, see +. + + The GNU General Public License does not permit incorporating your program +into proprietary programs. If your program is a subroutine library, you +may consider it more useful to permit linking proprietary applications with +the library. If this is what you want to do, use the GNU Lesser General +Public License instead of this License. But first, please read +. diff --git a/README.md b/README.md index 48ff7965..2602d02c 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,45 @@ # MkDocs_MiSTer -MiSTer FPGA Documentation site built using Material for MkDocs. + +https://MiSTer-devel.github.io/MkDocs_MiSTer/ + +MiSTer FPGA Documentation built in Material for MkDocs. + +## Useful resources + +* https://www.markdownguide.org/tools/mkdocs/ - Good guide on how to use markdown in mkdocs. +* https://www.mkdocs.org/user-guide/writing-your-docs/ - MkDocs reference + +## Software used + +* https://squidfunk.github.io/mkdocs-material/ - The static site generator used for this documentation site. (MIT License) +* https://github.com/byrnereese/mkdocs-minify-plugin - Minify plugin used. (MIT License) +* https://github.com/datarobot/mkdocs-redirects - Redirects plugin used. (MIT License) +* https://github.com/soulless-viewer/mkdocs-video - Embedded video plugin used. (MIT License) +* https://github.com/timvink/mkdocs-git-revision-date-localized-plugin - Git revision date plugin used. (MIT License) +* https://github.com/Guts/mkdocs-rss-plugin - RSS plugin used. (GPL 3.0 License) + +## Instructions for deploying a local environment + +Prerequisites: +* Python 3 +* Pip + +Make sure you update [python 3](https://www.python.org/downloads/) and [update pip](https://pip.pypa.io/en/stable/installation/). Then, `cd` into the root folder of this repo and install these modules: +``` +pip install mkdocs mkdocs-material mkdocs-minify-plugin mkdocs-redirects mkdocs-video mkdocs-git-revision-date-localized-plugin mkdocs-rss-plugin +``` +Deploy to local server from that root folder: +``` +mkdocs serve +``` +And it should give you a weburl in the terminal to go to --> http://127.0.0.1:8000 + +## Credits + +Huge thanks to [@tofukazoo](https://github.com/tofukazoo) (Jorge González) for helping me with the initial GitHub automation, lots of conceptual brainstorming, important early-stage debating, and finally the motivation and encouragement to get this project going! + +Thanks to [@Kitrinx](https://github.com/Kitrinx/), [@sentientsix](https://github.com/sentientsix), [@alanswx](https://github.com/alanswx/), [@MiSTerAddons](https://github.com/misteraddons), [@Tonurics](https://github.com/tonurics/), [@theypsilon](https://github.com/theypsilon/), and many more for so much help and advice with the content written and with the initial layout! + +Thanks to [@hewhoisred](https://github.com/hewhoisred) for supplying art and giving expert UI design and aesthetics advice! + +Thanks to [@sorgelig](https://github.com/sorgelig/) (Alexey Melnikov) for all of his amazing hard work on the MiSTer FPGA project that we all are so happy to enjoy! diff --git a/docs/advanced/audio.md b/docs/advanced/audio.md new file mode 100644 index 00000000..8eca4ee4 --- /dev/null +++ b/docs/advanced/audio.md @@ -0,0 +1,17 @@ +--- +hide: + - toc +--- + +The MiSTer has audio filters that you can use to make the audio sound less harsh and balanced to your ears. Some old game systems were not made for raw digital output, they had analog audio filters in place before the sound reached the speakers and your ears. These filters are generated using mathematical formulas to represent real common filters used in electronics. You can find all of the filters in the [Filters_MiSTer Github Repository](https://github.com/MiSTer-devel/Filters_MiSTer){target=_blank}. + +## Types of Filters + +`Arcade LPF` - The filters contained within this folder are designed to replicate the filtering of common arcade cabinets. Many arcade games' raw audio output is very harsh on the ears, and using the filters in here can help soften the sound to be more pleasing. 1st and 2nd refers to the amount of passes the filter goes through. LPF stands for "low-pass filter". The #khz tells you what frequency it starts filtering at. + +`Core Specific` - These are for specific cores. Currently there is only one core-specific filter and it is in order to replicate the filtering of one model of Super Nintendo. + +`General LPF` - These are more generalized low pass filters. The filters in this folder have a significantly different cutoff frequency when compared to the arcade cores. + +## Audio Filtering Example Video +![type:video](videos/sound-filters.mp4) diff --git a/docs/advanced/computer.md b/docs/advanced/computer.md new file mode 100644 index 00000000..5c154ebe --- /dev/null +++ b/docs/advanced/computer.md @@ -0,0 +1,69 @@ +There are many computer-core specific features and functionality to go over. Here are a few: + +# Computer core Internet and console connections + +Starting from 2018 may 7 release MiSTer supports serial (UART) connection from FPGA to Linux. Linux OS runs PPP or Console daemon on this connection allowing access the internet or Linux shell from FPGA cores. + +## Cores supporting serial connection +* **Minimig**. Tested on [Roadshow TCP/IP](https://misterfpga.org/viewtopic.php?f=4&t=2063&p=18598&hilit=Roadshow#p18598){target=_blank}, AmiTCP and Miami. + 1. AmiTCP provides more complete solution with ftpd daemon. There are many other 3rd party addons are based on AmiTCP, so it's advised to use this package. + 2. Roadshow works very well, it is fully compatible with AmiTCP and offers additional extensions. Follow these [Instructions](https://misterfpga.org/viewtopic.php?f=4&t=2063&p=18598&hilit=Roadshow#p18598){target=_blank} for complete setup. It is still a paid for and supported product, you can find more information [here](http://roadshow.apc-tcp.de/index-en.php){target=_blank}. + 3. Miami was successfully tested. The Miami settings that worked: use PPP connection via serial.device, set baud rate to 115200, RTS/CTS to on, and enable 8N1. Set modem to nullmodem. Manually enter an IP suitable for your lan ending in 254, e.g. 192.168.1.254. Manually add a DNS server, e.g. 8.8.8.8 for Google DNS. Term v4.7 has been used to test console connection. +* **ao486**. Currently only console connection has been tested using Dos Navigator's integrated Terminal and Kermit 3.15. PPP should work under Win95. +DOS tools are here : [dos_ftpd.zip](https://github.com/MiSTer-devel/ao486_MiSTer/raw/master/sw/dos_ftpd.zip){target=_blank}. The DOS FTP server included does not support passive mode, so set your client to use active. +* **C64**. Serial connection. + +OSD provides an option to switch between PPP and Console on these cores. +Both console and PPP are using baud rate 115200 8N1 mode with hardware RTS/CTS flow control for stability. + +## Console connection +Using this connection with supported terminal application on FPGA core, you can access the Linux shell and do some file managements or Linux settings if required. + +No special settings are required of Linux. + +## PPP connection +Using this connection core may have internet connection. More important, the core may run ftp daemon and provide access to its filesystem, so you can use FTP client on PC to move the files to/from the emulated system. + +PPP daemon uses **/media/fat/linux/ppp_options** (linux\ppp_options of PC) file. Most likely you don't need to modify it. Recent update assigns IPs automatically. Core gets .254 IP (for example 192.168.1.254). If you want other IP, then modify ppp_options file. + +For correct PPP work, make sure you see a network icon in Menu core before starting the other core. Otherwise PPP link won't get IPs. If you've started core earlier, then simply connect the core to PPP and disconnect. Next connection will get correct IP. Or you can switch UART mode in OSD to renew the IP. + +**NOTE:** I'm looking Amiga and MSDOS terminal supporting color and control codes of linux, so it will be possible to use Midnight Commander in terminal connection. If you know such terminal application, then let me know. + +## PPP connection in Windows 95 on ao486 +Unfortunately winsock and winsock2 provided by Microsoft do not work with the ppp connection when in Windows 95. + +The following steps will allow you to get it working. + +1. In the Mister System Menu ( Win/F12 ) set the "Uart Connection" to "PPP" and save it. +2. In Windows 95 ensure the COM1 device is installed in Start->Settings->Control Panel->System - Device Manager Tab, there should be a twisty called Ports(COM & LPT) and under that a "Communications Port (COM1)" +3. If it doesn't exist go to Start->Settings->Control Panel->Add/New Hardware and it should be automatically added. +4. Get the replacement PPP client + * Download the software. There are other newer versions available BUT be warned only version 3.0 will work. + * [Trumpet Winsock 3.0](https://winworldpc.com/product/trumpet-winsock/3x){target=_blank} - (I extracted the file from the disk image and uploaded it using the DOS ftp client documented above) +5. License the Software - This software is still shareware (time limited) please license it appropriately. Once you acquire a license you can put the details in Tcpman in the "Special" menu in "Password registration" +6. Configure Software + * Start Tcpman + * Under File-->PPP Options ensure all checkboxes are unchecked and the text boxes are blank. + * Under File-->Setup Enter an "IP Address" suitable for your LAN eg 192.168.1.254 and a "DNS Server(s)" 192.168.1.1 + * Under the Driver section select the PPP radio button and click on "Dialer settings..." + * In the "Dialer settings..." + * "COMM port" COM1 + * "Baud rate" 115200 +7. Using the software ( important, be patient ) + * Win95 is rather slow so let it start fully before starting the PPP manager (Tcpman) + * Once it is started it will begin syncing with PPP on the linux host... Be patient it takes a few seconds. + * When you see the PPP[C021] SND and RCV you can start your TCP/IP program + +I have found it to be a little complicated to get started, but once it is running it is rock solid and supports multiple client programs at once. + +## Serial connection on C64 +The following is an example for connecting to a BBS using Striketerm 2014. + +1. Start the C64 core (please note that custom kernels may remove functionality required, if in doubt use the built in kernel). +2. In the Mister C64 Menu ( Win/F12 ) set the "User Port" to "UART", and save it. +3. In the Mister System Menu ( Win/F12 ) set the "Uart Connection" to "Midi", "Remote", "TCP" and save it. +4. Load Striketerm 2014 from d64. Available from [here](https://csdb.dk/release/?id=130807){target=_blank} +5. Keep the defaults in the Main Menu (F1), ensure you are running at 2400 baud. +6. Save a BBS into the Addressbook (F5), you can get some from [here](http://cbbsoutpost.servebbs.com){target=_blank} +7. Surf the BBS very slowly... diff --git a/docs/advanced/console.md b/docs/advanced/console.md new file mode 100644 index 00000000..3dd7a58e --- /dev/null +++ b/docs/advanced/console.md @@ -0,0 +1,38 @@ +--- +hide: + - toc +--- + +The DE10-nano board has console port. The console allows you to login into Linux without a network connection and also provides some debug/info which sometimes useful to track the problems. + +Refer to the **UART-to-USB (USB Mini-B)** connector on the board right side in the picture below: + +![UART port location](img/layout_top.jpg) + +## Connect with Windows +Connect the DE10-nano board to a PC using the **UART-to-USB (USB mini type B)** connector next to micro-USB. The PC will recognize it as virtual COM port. Use any console application to connect to this COM port. I recommend [Putty](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html){target=_blank}. + +Verify that COM port settings are correct: + +* Speed (baud rate) - 115200 bits per second +* Data bits - 8 +* Stop bits - 1 +* Parity - none +* Flow control - none + +Here's a quick video for connections on Windows: + +![type:video](videos/console-connection.mp4) + +## Linux Connections + +1. Be sure to be a member of the **dialout** group. +2. Your serial port is likely to be **/dev/ttyUSB0** +3. Configure it: `$ stty -F /dev/ttyUSB0 115200 cs8 -cstopb -parenb -ixoff -ixon` +4. Look at the output while dumping it to a file: `cat /dev/ttyUSB0 | tee mr.log` + +Now mr.log has a copy of all the information shown in the screen. + +## U-Boot command prompt + +To interrupt u-boot and get into the u-boot command prompt once connected to the DE10-Nano, hold 'ESC' on the PC and then power on or reboot the Nano (using the reset button). Startup should be interrupted and you should see a '=>' prompt. Here you can edit the kernel boot options etc. diff --git a/docs/advanced/crt.md b/docs/advanced/crt.md new file mode 100644 index 00000000..d5b3b27e --- /dev/null +++ b/docs/advanced/crt.md @@ -0,0 +1,39 @@ +--- +hide: + - toc +--- + +There are a few different ways you can use a CRT display with the MiSTer. The two main methods are either using the VGA port on the Analog IO board or using a specific Direct Video HDMI to VGA adapter. + +## Configuration Table + +Here's a table that shows you what options correlate to what video connection, to make it a bit easier to decide what you need in order to connect to your CRT, and what settings are required in the MiSTer.ini to get it to work. + +| Analog Video Out | Ini: CSYNC | Ini: YPbPr | SoG Switch | VGA Scaler | Forced Scandoubler | +| --------------------- | ---------- | ---------- | ---------- | ---------- | ------------------ | +| RGBS Native | 1 | 0 | AUTO | 0 | 0 | +| RGBS Scan-doubled¹ | 1 | 0 | AUTO | 0 | 1 | +| RGBS Upscaled² | 1 | 0 | AUTO | 1 | 0 | +| RGBS Direct³ | 1 | 0 | N/A | 0 | 0 | +| RGBHV Native | 0 | 0 | AUTO | 0 | 0 | +| RGBHV Scan-doubled | 0 | 0 | AUTO | 0 | 1 | +| RGBHV Upscaled² | 0 | 0 | AUTO | 1 | 0 | +| RGBHV Direct³ | 0 | 0 | N/A | 0 | 0 | +| YPbPr Native | 0 | 1 | OVR | 0 | 0 | +| YPbPr Scan-doubled | 0 | 1 | OVR | 0 | 1 | +| YPbPr Upscaled² | 0 | 1 | OVR | 1 | 0 | +| YPbPr Direct³⁴ | 0 | 1 | N/A | 0 | 0 | +| S-Video⁵ | 1 | 0 | N/A | 0 | 0 | +| Composite⁵ | 1 | 0 | N/A | 0 | 0 | + +¹ Scan-doubled = 2x resolution (e.g. 240p > 480p) +² Upscaled resolution = video_mode +³ External "direct video" (HDMI to VGA) adapter required - native resolution only (no upscaling or scan-doubling +⁴ External "direct video" adapter requires modification to pass Sync on Green (SoG) +⁵ External RGB to NTSC/PAL converter required + +Credit: Porkchop Express + +## Analog IO Add-on board + +## Direct Video Adapter diff --git a/docs/advanced/directvideo.md b/docs/advanced/directvideo.md new file mode 100644 index 00000000..0e2bfe92 --- /dev/null +++ b/docs/advanced/directvideo.md @@ -0,0 +1,61 @@ +# Direct Video +Since autumn of 2019 there is a method for outputting analog video called *Direct Video* that doesn't require you to install the IO Board in your MiSTer. This new method offers **same** minimal latency to the VGA port from the IO Board and even better color depth in some cores. To enjoy it, you just need to activate the feature in your mister.ini file and attach a DAC to your HDMI port. + +![picture](img/direct-video-dac.jpg) + +*You may use an HDMI-to-VGA converter similar to this one.* + +*NOTE*: as of 2021/06/27 it seems very hard to find devices which are compatible with VGA to SCART adapters. Devices which work with VGA are still easy to find. More info here: https://github.com/MiSTer-devel/Main_MiSTer/issues/410 + +## Compatibility + +*Direct Video* is compatible with most current cores and will be supported in all future cores coming to MiSTer. + +RGBs, RGsB and YPbPr are supported, although YPbPr has less display compatibility in *Direct Video* mode compared to YPbPr from the IO Board. + +Note that output resolution and format can vary from core to core. See [the analog video configuration table](crt.md/#configuration-table) for more information. + +## How to Use + +First you need a simple DAC with VGA output. Those based on the chip AG6200/AG6201 (like the one in the picture) are proven to work fine and are fairly inexpensive and easy to find. Also many of them output analog audio too. The only thing we recommend is to not hotplug them or pull them out from your MiSTer while it is still **ON**, since you might damage your HDMI port in the process. + +Then you need to add the following line to your [mister.ini](ini.md) file: + +`direct_video=1` + +This activates the *Direct Video* feature when the system starts. Once it's enabled, it allows your HDMI port to output the raw and unprocessed digital audio/video signal from the loaded core, which is consumed by your DAC. MiSTer will not work with your HD TV or monitor while this mode is enabled, since they require a standard HDMI signal to work, and the zero-lag *Direct Video* signal **IS NOT** standard HDMI. + +The resulting analog video signal from your DAC should be compatible with standard CRTs if the core loaded supports standard CRT refresh frequencies (see [analog video compatibility](Analog-video-output-compatibility) for more details). But there is still a bit of additional configuration you need to do depending on which kind of analog video signal you want to use. + +## Setup for RGB signals + +For analog RGB output, you'll want to enable composite sync on the HSync signal in your mister.ini (`composite_sync=1`). After that, you are good to plug in an RGB-compatible VGA-SCART cable to your TV. + +For optimal results, [Retro Access](https://retro-access.com/products/mister-io-scart?_pos=1&_sid=97cb11000&_ss=r){target=_blank} sells SCART and BNC cables specifically for use with MiSTer. + +**DISCLAIMER:** Please be aware that many VGA DACs may output a sync signal at **3 volts _or more_** on pin 13 (HSYNC/CSYNC) even when being used in *Direct Video* mode! You will need a 470 ohm resistor on the corresponding SCART sync pin to attenuate this signal to levels that are safe for all video equipment. A variety of professional video equipment can have wide tolerances for higher voltage sync signals but other devices, especially external scalers like the OSSC or XRGB Mini Framemeister, can be worn out and reduced to a non-working state by repeated use with higher-voltage sync signals. Unless you are 100% certain your equipment can tolerate higher voltage signals, it is _strongly_ recommended that you either purchase a cable that has a 470 ohm resistor inline or add one yourself. Retro Access MiSTer SCART cables, for example, come with a resistor inline by default. + +## Setup for YPbPr signals + +YPbPr - also known as Component Video - is available in *Direct Video* mode but has limited compatibility. This is due to limitations of HDMI-to-VGA DACs, which were not meant to produce signals in the YPbPr color space in the first place, resulting in signals that are slightly out-of-spec. It is possible that your display will accept the *Direct Video* YPbPr signal with no issue, but it may also appear bright pink [due to the way many displays process such signals](https://github.com/MiSTer-devel/Main_MiSTer/issues/210#issuecomment-622672178){target=_blank}. For higher YPbPr compatibility you may prefer RGB mode with an external RGB-to-YPbPr transcoder instead, or YPbPr via the IO Board. + +To use YPbPr in *Direct Video* mode, you'll need to enable `composite_sync` and `ypbpr` in your [mister.ini](Configuration-Files) file. + +You'll also need to add a sync-on-green circuit on your VGA connection. Sync-on-green circuits can be very simple; you just need a diode (1N4148) and a 1k resistor. +![picture](img/sync-on-green-circuit.png) +*Connection: from HSync -> anode of diode, cathode of diode -> resistor, resistor to Green signal.* + +## Doubling frequency + +This is a handy way to use those modern monitors that have VGA input but are typically not compatible with 15KHz signals, and require 31KHz analog video. In case you need it, you just have to set `forced_scandoubler=1` in your mister.ini to turn a 15KHz signal into a 31Khz one (See which cores output 15KHz video [here](Analog-video-output-compatibility)). + + +## Color Depth + +*Direct Video* produces a 24bit color signal, which is superior to the 18bit signal coming from the IO Board. However, few cores use 24bit color, so the improved color depth may not make much of an impact depending on the cores you run. + +Also, most cheap DACs, like the ones based on the chip AG6200, don't produce Full Range RGB. They instead produce Limited Range RGB (16-235) or much more commonly a nonspec Limited Range variant (16-255). In order to compensate for this, you may want to configure the `hdmi_limited` option in your mister.ini to adjust the signal being sent to your DAC. + +- Full Range (0-255): `hdmi_limited=0`. +- Limited Range (16-235): `hdmi_limited=1`. +- Limited Range common DAC variant (16-255): `hdmi_limited=2`. diff --git a/docs/advanced/img/direct-video-dac.jpg b/docs/advanced/img/direct-video-dac.jpg new file mode 100644 index 00000000..1358550b Binary files /dev/null and b/docs/advanced/img/direct-video-dac.jpg differ diff --git a/docs/advanced/img/layout_top.jpg b/docs/advanced/img/layout_top.jpg new file mode 100644 index 00000000..6c45a5a2 Binary files /dev/null and b/docs/advanced/img/layout_top.jpg differ diff --git a/docs/advanced/img/sync-on-green-circuit.png b/docs/advanced/img/sync-on-green-circuit.png new file mode 100644 index 00000000..d4e0161b Binary files /dev/null and b/docs/advanced/img/sync-on-green-circuit.png differ diff --git a/docs/advanced/ini.md b/docs/advanced/ini.md new file mode 100644 index 00000000..bfeb474a --- /dev/null +++ b/docs/advanced/ini.md @@ -0,0 +1,67 @@ +The [MiSTer.ini configuration file](https://github.com/MiSTer-devel/Main_MiSTer/blob/master/MiSTer.ini){target=_blank} contains global settings and is capable of storing core-specific settings for the MiSTer. We'll go over each of the Global settings here and then show you how to make exceptions for those global settings for each core. Then we'll describe some core-specific settings that can be used for core exceptions only. + +## General Video Settings + +`vscale_mode` - Changes how the image is scaled to the screen. 0 will fit the whole image to screen, 1 is 1:1 integer scaled, 2 uses 0.5 steps to scale, and 3 uses 0.25 steps to scale. + +`vscale_border` - Sets an overscan border to the screen in number of pixels (1-399) + +`hdmi_limited` - Changes the color range output over HDMI. 0 = `0-255`, 1 = `16-235`, and 2 = `16-255`. A setting of 2 can be useful if you have problems with some Digital Video adapters. It can also help if your screen has a dynamic backlight and you want to brighten things up, to change the setting to 1. + +`fb_size` - Effects the scaling of things drawn to the Linux framebuffer, such as when you run scripts. Best left to 0 for automatic. + +`video_mode` - Sets the resolution for HDMI and VGA_Scaler output. This can be one of the premade values from 0-13 or it can be a custom video mode. See the notes in the [.ini Master](https://github.com/MiSTer-devel/Main_MiSTer/blob/2b0b8a1422540fa5c49e6a71a694848143341c87/MiSTer.ini#L75){target=_blank} for custom video mode syntax. There is also a useful custom video mode tool by morf77 [available here](https://morf77.pythonanywhere.com/){target=_blank} which can be used in conjunction with a [modeline calculator](https://arachnoid.com/modelines/){target=_blank}. + +`video_info` - Number of seconds that it will display the video info in the top left corner of the screen whenever the resolution or frequency has changed. + +`vsync_adjust` - Adjusts the buffer settings for the frames sent to the display. For more details on how this works, see the [Video Configuration](../basics/video.md#vsync_adjust){target=_blank}'s vsync_adjust section. Essentially, the values of `0-2` are in order of most compatible+highest lag to least compatible+lowest lag. + +`refresh_min` - Forces a minimum refresh rate. + +`refresh_max` - Forces a maximum refresh rate. + +`` - + +## Analog Video Settings + +`forced_scandoubler` - VGA output will always run in 31kHz mode (scandoubled) if this setting is turned on, useful for computer CRT's. + +`ypbpr` - Changes the VGA output to a YPbPr signal. + +`composite_sync` - Sends the sync signal on Hsync over VGA output, needed for certain configurations. + +`vga_scaler` - Sends the scaler output to the VGA port (either Analog IO or Direct Video). This is usually used with computer CRTs and other 31kHz displays which are not compatible with 240p TV signals. + +`menu_pal` - Forces the Menu core to run in PAL mode. + +`direct_video` - This changes the HDMI output to an analog signal, only supported with certain Direct Video Adapters that have AG62xx chipsets. If you have issues with color or no image, in addition to checking `composite_sync` and `ypbpr` options, you can also try changing `hdmi_limited` to `1`. If you are using `ypbpr` with component cables, the Direct Video adapter will need a modification to combine HSYNC and Green in order to work. + +`fb_terminal` - Best left at 1. If you have issues with running scripts on a CRT or Analog display, try switching this to 0 to see if that helps. + +## Audio Settings + +`hdmi_audio_96k` - Changes the HDMI audio sampling rate from 48kHz (default) to 96kHz. This can help with the audio of some systems that have strange sampling rates (like Turbografx-16's sampling rate of 32.088kHz for instance). + +`dvi_mode` - DVI mode over the HDMI connection, this disables audio transmission over HDMI when turned on. + +## Controller Settings + +`mouse_throttle` - Can be used to change the speed of your mouse (1-100). Good for very sensitive mice. + +`gamepad_defaults` - + +`bt_auto_disconnect` - Amount of minutes of inactivity before Bluetooth disconnects automatically. Default is 0 (off). + +`bt_reset_before_pair` - Resets bluetooth adapter before pairing dialog. If you enable this some input devices may get shutdown after a reset. + +## Menu Settings + +`rbf_hide_datecode` - Hides the date codes from the core names in the core selection menu. + +`osd_timeout` - The length of time the OSD is displayed when brought up and no inputs have been pressed. 0 - never timeout, and the range of values are 5-3600 seconds. + +`osd_rotate` - Rotate the OSD. Useful for when you rotate your monitor for certain Arcade cores. 0 - no rotation, 1 - rotate right (+90°), and 2 - rotate left (-90°). + +## Debug Settings + +`log_file_entry` - Writes filename under the curse in browser for use by external integrations. diff --git a/docs/advanced/lag.md b/docs/advanced/lag.md new file mode 100644 index 00000000..5f7ff171 --- /dev/null +++ b/docs/advanced/lag.md @@ -0,0 +1,87 @@ +A common concern among retro enthusiasts is whether a device of this sort has _lag_ and whether it will create a less desirable experience compared to original hardware. + +Every electronic equipment exhibits some kind of _latency_, but it only becomes problematic if this latency causes frames to be missed. A frame is typically 16ms for a system using a 60 frames per second (60 Hz) display. + +Lag is only problematic in a few specific cases: +* Some older games were designed to rely on extremely quick response times (e.g. Punch-Out on NES). +* If the latency is different between two players, it could introduce an unfair advantage. +* Lag that isn't constant can be an issue on games that require precise movement. (Most players can adapt to lag that is consistent.) + +There are three major categories of lag. **Input**, which involves controllers, mouse, etc, **Processing**, which would involve buffering in the core, execution or delays in code and **Display** which involves the output of the video to your display device. + +For a more detailed overview of lag and exploration of it, please refer to this page: + +[https://inputlag.science/](https://inputlag.science/){target=_blank} + +### Input +For input, MiSTer primarily uses USB. In this case the overall input lag is the sum of the lag caused by the USB polling and the lag caused by the controller itself, how quickly it processes the signals. The latter is outside the scope of MiSTer and can only be improved by using a better controller. On the MiSTer side only the lag caused by the USB polling can be reduced if the connected USB device supports a lower polling interval. The polling interval is measured in Hz and indicates how often a USB device is polled per second. At 1000 Hz, a USB device is polled 1000 times per second, which means the additional lag caused by the polling is 1 s / 1000 = 1 ms in the worst case and 0.5 ms on average. This is a great improvement compared to the default value of 125 Hz, where a USB device is polled 125 times per second, which means the additional lag caused by the polling is 1 s / 125 = 8 ms in the worst case and 4 ms on average. + +If a game is rendered at 60 frames per second, a single frame takes 1 s / 60 ≈ 16 ms to process. One might think that any polling interval below 16 ms would be perfect; however, USB polling happens independently of the vertical sync. Therefore, even with a 1 ms polling interval, there is a chance of 1/16 that the whole frame will be missed and input will be processed on the next frame. The longer the polling interval, the greater the odds of a missed frame. With a polling interval of 8 ms, the odds of input missing a frame are 50%. Native polling rates and input response vary across consoles and even games. + +### Processing +This is one core advantage of emulation using FPGAs. Unlike software emulators which go through a cycle of executing, and then waiting for a screen refresh, FPGA cores run in real time, as the original hardware did. This means that cores don’t have CPU bottlenecks to slow them down arbitrarily or require additional large buffers to hold data under most circumstances. + +### Display +MiSTer’s two primary display outputs are analog and HDMI. + +The analog output is driven as the original system would have, with no buffering, and so it will be effectively identical to the latency of a real console. From this point of view, the analog output cannot have any form of lag. + +When using HDMI output the image must be scaled up to fit the higher resolutions, which requires additional processing. The MiSTer scaler has options which impact its latency. Using `vsync_adjust=2` in the ini file will result in about 4 scanlines of latency, while 0 or 1 will result in up to roughly 2 frames of latency, with the added advantage of being more compatible with displays. + +In addition your own television or monitor may introduce more latency, but this varies by device and no definite number can be given on that here. + +In summary, if lag is critical to you, **it's best to play on a CRT using a recommended and widely-tested USB controller.** Some users have tested and ranked USB controllers by performance; you can see their results [here](https://github.com/eniva/MisSTer_Guides/wiki/USB-Controllers-Performance-Ranking){target=_blank}. An alternate thorough list of tested controllers by misteraddons is also available [here](https://rpubs.com/misteraddons/inputlatency){target=_blank}. + +Do keep in mind, however, that even over HDMI MiSTer is capable of providing a better experience than many other devices. + +## Reducing Lag + +### Video lag + +MiSTer offers options in how to configure its HDMI upscaler, making a tradeoff between compatibility and low latency. +These can be set in the MiSTER.INI file at the root of the SD card: + +* `vsync_adjust=2` is the best option if it is compatible with your TV. This mode uses the original refresh rate and pixel clock of the core, resulting in no additional latency. +* `vsync_adjust=1` is the second best option, but it adds up to 2 frames of latency. This mode uses a framebuffer but maintains the system's original vsync and varies the pixel clock per core. +* `vsync_adjust=0` is the lesser option, but the most compatible. Up to 2 frames of latency and less smooth scrolling. This mode guarantees 60 hz output with an NTSC standard pixel clock. + +### Input lag + +USB controllers usually have an interval value which the host (MiSTer Linux kernel) respects to poll their inputs at. Most USB devices can actually perform better by being polled more often without any side effects. + +To set a higher USB polling rate, you need to go to the "linux" subdirectory on your SD card and rename "u-boot.txt_example" to "u-boot.txt". The aforementioned file contains the following options, which should only be changed if you are encountering problems: +```bash +v=loglevel=4 usbhid.jspoll=1 xpad.cpoll=1 +``` +**loglevel**: 4 is the default value. You can set this to 9 to get debugging messages with dmesg command via SSH. If you just want to know which values of usbhid.jspoll and xpad.cpoll are applied to your controller, there are easier ways to achieve this (see below). + +**usbhid.jspoll**: specifies the interval for USB HID controllers, usually DirectInput. + +* 0 is the default value MiSTer uses (even when there is no "u_boot.txt"). In this case the requested value from the controller is used. +* 1 is the recommended value (which means 1000/1 = 1000 Hz polling rate). However, if you ever encounter any issues, try higher integer values. The higher the interval, the higher the possible lag. This shouldn't go above 8 (which means 1000/8 = 125 Hz polling rate). +* To see which value is applied to your controller, you can run ```systool -m usbhid -A jspoll``` from the Linux shell. + +**xpad.cpoll**: specifies the interval for USB XInput controllers. Most popular controllers use this. There is no practical difference here. XInput is for Microsoft's Xbox consoles and PC. + +* 0 is the default value MiSTer uses (even when there is no "u_boot.txt"). In this case the requested value from the controller is used. +* 1 is the recommended value (which means 1000/1 = 1000 Hz polling rate). However, if you ever encounter any issues, try higher integer values. The higher the interval, the higher the possible lag. This shouldn't go above 8 (which means 1000/8 = 125 Hz polling rate). +* To see which value is applied to your controller, you can run ```systool -m xpad -A cpoll``` from the Linux shell. + +## What is the fastest controller I can get? + +Almost any standard USB controller will work well with MiSTer, however there is a short list of excellent controllers that we can suggest based on user feedback and input lag testing: + +* 8bitdo M30 2.4g connected in wired mode +* Sony DS4 in wired mode +* Hori Fighting Commander (later revisions), either PS4 or XBOX1 variant is fine; pick your favorite +* DIY USB adapter using open source firmware available [here](https://github.com/MiSTer-devel/Retro-Controllers-USB-MiSTer){target=_blank} + +Generally speaking, while Bluetooth connected devices will work fine, you can expect the highest amount of input latency while using your controller in this way. + +Please keep in mind, “high latency” controllers *should* add, at most, 16 ms (1/60th of a second) or one frame (or rarely, depending on the controller, 32ms) of lag, and not constantly, to your experience, which is not a lot of lag, so if you’re not the type of person who notices that, you can safely just use any decent USB controller. Variable lag (the input response varying between 1 and 3 frames, for instance) is more noticeable than consistent lag. There are very few controllers which add more than 1 frame of lag. + +There is no definitive fastest controller that you can get, but there are quite a few at the top of the list. You can, again, check MiSTerAddons and Lemonici's [MiSTer Input Latency Chart](https://rpubs.com/misteraddons/inputlatency){target=_blank} for a definitive community sourced list of controllers tested with MiSTer with a separate device that uses the DE10-Nano's headers to get an objective result. + +Please see these article for more information about USB controller lag +* https://medium.com/@WydD/controller-input-lag-how-to-measure-it-1ebfd2c9d60 +* https://inputlag.science/ diff --git a/docs/advanced/midi.md b/docs/advanced/midi.md new file mode 100644 index 00000000..2e17547e --- /dev/null +++ b/docs/advanced/midi.md @@ -0,0 +1,64 @@ +When running the Minimig and ao486 cores, once a ALSA compatible USB MIDI device is attached, two additional ‘UART Connection’ menu options (‘USBMIDI’ and ‘USBMIDI-38K’) will be available in addition to ‘None’, ‘PPP’ and ‘Console’. + +## Minimig + +‘USBMIDI’ - This option is used with the Amiga / Minimig core. This option sets the UART connection speed to 31250 baud which is the standard MIDI speed. + +Many Amiga applications and most games don’t require any additional drivers for MIDI. Some “newer” applications may require the CAMD driver. + +[Aminet : CAMD](http://aminet.net/package/mus/midi/camd){target=_blank} + +## ao486 + +‘USBMIDI-38K’ - This option is used with the ao486 core. This option sets the UART Connection speed to 38400 baud. (The MIDI speed of 31250 baud is not a standard speed DOS PC UARTs were capable of doing) + +While some sequencer applications and Microsoft Windows may support MIDI on the serial port, DOS games typically require a MPU-401 interface which ao486 unfortunately lacks. In lieu of hardware MPU-401 capability the SoftMPU TSR can be used with a good degree of success. + +[SoftMPU](http://bjt42.github.io/softmpu/){target=_blank} + +## SoftMPU + +SoftMPU requires the QEMM memory manager be installed. For testing QEMM 8.03 was used. QEMM “stealth” option seems to be incompatible with ao486 so it is advisable to skip that part of the optimize process. It’s a good idea to run the QEMM optimize application again after installing SoftMPU (in the AUTOEXEC.BAT) to get as much of the lower 640K conventional RAM free as possible. + +Although less common, some DOS games and applications require MPU-401 interrupts. This option can break compatibility with others software not requiring interrupts. + + +Starting SoftMPU without MPU-401 interrupts: + + SOFTMPU.EXE /MPU:330 /OUTPUT:COM1 + +Starting SoftMPU with MPU-401 interrupts: + + SOFTMPU.EXE /SB:220 /IRQ:5 /MPU:330 /OUTPUT:COM1 + +The Rev.0 Roland MT-32 used in testing required the ‘DELAYSYSEX’ switch to prevent buffer overflow for certain games but made Sierra games upload sysex commands excessively slowly. This is not necessary for General MIDI modules and newer revision MT-32s. + + SOFTMPU.EXE /MPU:330 /DELAYSYSEX /OUTPUT:COM1 + +## MidilLink + +The 'midilink' daemon currently supports following switches / options: + +``` +TESTSER - this option sends a test message to the serial port once + the daemon is started. + +TESTMIDI - this option sends a middle 'c' note to the MIDI device + once the daemon is started. + +QUIET - this option suppresses MIDI debug output. + +38400 - this option sets the serial speed to 38400 baud + (default is 31250 baud) - used with ao486 core. +``` + +[MidiLink Github](https://github.com/bbond007/MiSTer_MidiLink){target=_blank} + +## MIDI Adapters reported to work + +* Creative EMU XMIDI (Known to mangle SYSEX messages) +* Roland UM-ONE +* M-Audio Midisport Uno + +## MT32-pi Video Example +![type:video](videos/mt32-pi.mp4) diff --git a/docs/advanced/multibutton.md b/docs/advanced/multibutton.md new file mode 100644 index 00000000..795bede6 --- /dev/null +++ b/docs/advanced/multibutton.md @@ -0,0 +1,135 @@ +When overriding gamepad settings inside a core it is possible to define button combinations (e.g. A+B) if you have enough physical buttons. + +To allow for this, MiSTer will ask if you want to setup "alternate mappings" after defining a gamepad. + +Alternate mappings are active in parallel and allow two kinds of abilities: map two physical button to the same core button (e.g. alternate button for Start), or map one physical button to two-button combo in the core (e.g. map physical X to thr core's A+B). + +## Bind core button to two physical buttons + +The simplest is to map an extra physical button. Only this additional button needs to be defined in the alternate map, as follows: + +| **map** | **d-pad** | **A** | **B** | +|:--------|:---------|:------|:------| +|**main**|_define_|Btn 1|Btn 2| +|**alt**|_skip_|_skip_|Btn 3| + +The result of using this setup ia that you will have physical buttons 2 and 3 mapped to the core button B. + +This also works with gamepad directions. For example, for games that use Up as a jump button, it is possible to map a physical third button to jump. + +## Bind physical button to core button combo + +A more advanced setup is to use both mappings in parallel to make one physical button push two core buttons at the same time. + +See the table below: + +| **map** | **d-pad** | **A** | **B** +|:--------|:---------|:------|:------| +|**main**|_define_|Btn 1|Btn 3| +|**alt**|_skip_|Btn 3|Btn 2| + +The result of this is that Button 1 will be A, Button 2 will be B, and Button 3 will be A+B. + +This is particularly useful for the Neogeo core where some fighting games use A+B and C+D as "strong hit". + +(note: unfortunately NeoGeo games are not consistent with each other - so it is not possible to set one mapping for all games) + +## Example: NeoGeo Breakers / Breakers' Revenge + +Assume a six button arcade controller (for Street Fighter 2) with 3 punch buttons on top and 3 kick buttons below. + +We will map the buttons so that Breakers / Breakers' revenge has the same kind of layout. + +This particular game uses the following attack buttons: +* A: Weak Punch +* B: Weak Kick +* C: Strong Punch +* D: Strong Kick + +In addition, most characters have an extra "command" move mapped to: +* Weak Punch + Strong Punch +* Weak Kick + Strong Kick + +To match the Street Fighter 2 layout, we can assign this across six buttons: + +| **-** | **Weak** | **Strong** | **Weak+Strong** | +|:--------|:---------|:-----------|:----------------| +|**Punch**| A | C | A + C | +|**Kick** | B | D | B + D | + +Which translates to the following buttons: + +| **-** | **Weak** | **Strong** | **Weak+Strong** | +|:--------|:---------|:-----------|:----------------| +|**Punch**|Btn 1 | Btn 2 | Btn 3 | +|**Kick** |Btn 4 | Btn 5 | Btn 6 | + +To obtain this, input the following assignment during main and alternate mapping: + +| **map** | **d-pad** | **A** | **B** | **C** | **D** | +|:--------|:----------|:------|:------|:------|:------| +|**main** |_define_ | Btn 1 | Btn 4 | Btn 3 | Btn 6 | +|**alt** |_skip_ | Btn 3 | Btn 6 | Btn 2 | Btn 5 | + +(in alternate mapping, d-pad and all other buttons can be skipped) + +## Example: NeoGeo King of Fighters / Fatal Fury Special + +Both of these game use the same attack layout as Breakers but their button combination differs: + +| **-** | **Weak** | **Strong** | **Combo** | +|:--------|:---------|:-----------|:----------------| +|**Punch**| A | C | A + B | +|**Kick** | B | D | C + D | + +To map this, we need to switch things around a little bit: + +| **map** | **d-pad** | **A** | **B** | **C** | **D** | +|:--------|:----------|:------|:--------|:--------|:------| +|**main** |_define_ | Btn 1 | _Btn 3_ | _Btn 2_ | Btn 6 | +|**alt** |_skip_ | Btn 3 | _Btn 4_ | _Btn 6_ | Btn 5 | + +## Example: NeoGeo Samurai Shodown + +This game has yet another layout, changing the order of base attacks: + +| **-** | **Weak** | **Medium** | **Strong** | +|:--------|:---------|:-----------|:----------------| +|**Slash**| A | B | A + B | +|**Kick** | C | D | C + D | + +We can map this as follows: + +| **map** | **d-pad** | **A** | **B** | **C** | **D** | +|:--------|:----------|:------|:--------|:--------|:------| +|**main** |_define_ | Btn 1 | Btn 3 | _Btn 4_ | Btn 6 | +|**alt** |_skip_ | Btn 3 | _Btn 2_ | Btn 6 | Btn 5 | + +## Counter Example: The Last Blade 1 and 2 + +Very similar to the above but a different button combo: + +| **-** | **Weak** | **Medium** | **Special** | +|:--------|:---------|:-----------|:----------------| +|**Slash**| A | B | _B + C_ | +|**Kick** | C | D | C + D | + +In this case, it is not possible to map C three times _so we must choose whether to map B+C or C+D_. + +#### Option 1: Mapping B+C to button 3: + +| **map** | **d-pad** | **A** | **B** | **C** | **D** | +|:--------|:----------|:------|:--------|:--------|:------| +|**main** |_define_ | Btn 1 | Btn 2 | Btn 3 | Btn 5 | +|**alt** |_skip_ | _skip_| Btn 3 | Btn 4 | _skip_| + +(Btn 6 remains unassigned) + +#### Option 2: Mapping C+D to button 6: + +| **map** | **d-pad** | **A** | **B** | **C** | **D** | +|:--------|:----------|:------|:--------|:--------|:------| +|**main** |_define_ | Btn 1 | Btn 2 | Btn 6 | Btn 5 | +|**alt** |_skip_ | _skip_| _skip_ | Btn 4 | Btn 6| + +(Btn 3 remains unassigned) diff --git a/docs/advanced/network.md b/docs/advanced/network.md new file mode 100644 index 00000000..74056cbf --- /dev/null +++ b/docs/advanced/network.md @@ -0,0 +1,43 @@ +There are multiple advanced networking features that the MiSTer can utilize. Here we will go over quite a few of them. + +## CIFS Share Mounting +The MiSTer can mount a network share from another computer or server as if it were storage. There are two scripts that are used by the MiSTer for CIFS mounting and unmounting. + +[cifs_mount.sh](https://raw.githubusercontent.com/MiSTer-devel/Scripts_MiSTer/master/cifs_mount.sh){target=_blank} + +This script mounts the desired network share to the MiSTer in such a way that any identical folders from `/media/fat` will be put on a lower priority and you will see the ones from the network share in place of the ones on your MicroSD. See [Core Paths](../cores/paths.md) for more specific information as to how this hierarchy functions. + +[cifs_umount.sh](https://raw.githubusercontent.com/MiSTer-devel/Scripts_MiSTer/master/cifs_umount.sh){target=_blank} + +This script will unmount the network share when ran. + +## RetroNAS +A project was launched that makes it easier to get a network attached storage (NAS) device up and running which was focused solely on retro gaming device compatibility. The MiSTer was one of their primary focuses and it works quite well. All you need is a Raspberry Pi4 and some kind of external hard drive storage device. Remember: NAS IS NOT BACKUP! You could lose data if you rely solely on a NAS for important data. They have a good [installation guide](https://github.com/danmons/retronas/wiki/Installing-RetroNAS){target=_blank} that is simple to follow and [MiSTer-specific instructions](https://github.com/danmons/retronas/wiki/MiSTer-FPGA){target=_blank} to help get you started. They also have video guides available on Youtube for [installation](https://www.youtube.com/watch?v=szA-MSabplc){target=_blank} and [MiSTer FPGA-specific configuration](https://www.youtube.com/watch?v=OrTctA-5kqk){target=_blank} if you prefer. + +## Static IP Address configuration +Currently the best way to do this is using `connmanctl` (try `connmanctl help` for more info). +* Create /var/lib/connman directory so changes will persist across reboots +``` +# mkdir /var/lib/connman +``` +* Find your on-board network service name. +``` +# connmanctl services +*AO Wired ethernet_020304050607_cable +``` +* Setup IP address (e.g. `192.168.1.123`, should be unused), subnet mask (e.g. `255.255.255.0`) and gateway (e.g. `192.168.1.1`, typically your router IP address). To configure the right device use the service name returned from above command (e.g. `ethernet_020304050607_cable`). This will disable the use of DHCP. +``` +# connmanctl config ethernet_020304050607_cable --ipv4 manual 192.168.1.123 255.255.255.0 192.168.1.1 +``` +* Setup one or more DNS server(s) (e.g. `192.168.1.1` from your router, `8.8.8.8` from Google DNS. +``` +# connmanctl config ethernet_020304050607_cable --nameservers 192.168.1.1 8.8.8.8 +``` +You could write a script to help with typing and remembering your settings. + +> You can also setup your on-board network connection by editing `/etc/network/interfaces`. This is currently not advised. Because if you have a DHCP server in your network, the network stack will still contact the DHCP server and assign the returned IP address regardless, leading to usually unwanted behavior. + +## Re-Enabling DHCP +``` +# connmanctl config ethernet_020304050607_cable --dhcp +``` \ No newline at end of file diff --git a/docs/advanced/troubleshooting.md b/docs/advanced/troubleshooting.md new file mode 100644 index 00000000..dfd9f820 --- /dev/null +++ b/docs/advanced/troubleshooting.md @@ -0,0 +1,14 @@ +--- +hide: + - toc +--- + +## Fixing missing certs + +If you are unable to wget as instructed above, this might be because you are missing security certificate files. The default system comes with no security certificate files, which is a bit annoying, as you need to add --no-check-certificate on wget to download anything HTTPS. Lets fix that: + +1. Open the linux terminal/command prompt with F9, use `root` as your username and `1` as your password. +2. Type `cd /etc/ssl/certs` and press enter. +3. Type `wget --no-check-certificate https://curl.haxx.se/ca/cacert.pem` and press enter + +Assuming it downloaded correctly, you can _now_ use wget as nature intended! diff --git a/docs/advanced/videos/console-connection.mp4 b/docs/advanced/videos/console-connection.mp4 new file mode 100644 index 00000000..3cee7d74 Binary files /dev/null and b/docs/advanced/videos/console-connection.mp4 differ diff --git a/docs/advanced/videos/mt32-pi.mp4 b/docs/advanced/videos/mt32-pi.mp4 new file mode 100644 index 00000000..f607ba88 Binary files /dev/null and b/docs/advanced/videos/mt32-pi.mp4 differ diff --git a/docs/advanced/videos/sound-filters.mp4 b/docs/advanced/videos/sound-filters.mp4 new file mode 100644 index 00000000..e246bfd9 Binary files /dev/null and b/docs/advanced/videos/sound-filters.mp4 differ diff --git a/docs/assets/favicon.ico b/docs/assets/favicon.ico new file mode 100644 index 00000000..3205c07c Binary files /dev/null and b/docs/assets/favicon.ico differ diff --git a/docs/assets/logo_small.png b/docs/assets/logo_small.png new file mode 100644 index 00000000..0ac4073f Binary files /dev/null and b/docs/assets/logo_small.png differ diff --git a/docs/assets/logo_vector.svg b/docs/assets/logo_vector.svg new file mode 100644 index 00000000..4c69f994 --- /dev/null +++ b/docs/assets/logo_vector.svg @@ -0,0 +1,210 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/assets/mister_kun_bw.svg b/docs/assets/mister_kun_bw.svg new file mode 100644 index 00000000..63689109 --- /dev/null +++ b/docs/assets/mister_kun_bw.svg @@ -0,0 +1,82 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/basics/bluetooth.md b/docs/basics/bluetooth.md new file mode 100644 index 00000000..f7f062ea --- /dev/null +++ b/docs/basics/bluetooth.md @@ -0,0 +1,20 @@ +--- +hide: + - toc +--- + +Bluetooth adapters and using controllers over bluetooth is supported on the MiSTer. + +## Compatible adapters + +Generally speaking, most bluetooth 4.0 adapters use one of two similar chips, the CSR8510 and the BCM20702, and these are compatible. Bluetooth 5.0 adapters are a little different, but many are compatible as well. Here is a list of a few known compatible adapters: + +* [ASUS USB-BT500 (5.0)](https://www.amazon.com/dp/B08DFBNG7F){target=_blank} +* [Edimax BT-8500 (5.0)](https://www.amazon.com/Edimax-BT-8500-Bluetooth-Supports-Controllers/dp/B08M1VJHVD/){target=_blank} +* [ZEXMTE Long Range USB Bluetooth (5.0)](https://www.amazon.com/ZEXMTE-Bluetooth-Adapter-Keyboard-Headphones/dp/B09D7W918Q){target=_blank} + +There are many more that work than just these. Please note that some hardware revisions may change the compatibility of even the adapters in this list, your results may vary. For the most part, most adapters seem to work fine. + +## How to pair your Bluetooth controller or Keyboard + +This is the easy part. Simply press the F11 key on a keyboard that is already connected to the MiSTer and the pairing menu will pop up. Put your controller into pairing mode and wait. The MiSTer should find it momentarily and connect to it. You may need to define your inputs for this new controller, even if it's been plugged directly into the MiSTer before as it is seen as a different controller over bluetooth. diff --git a/docs/basics/cd.md b/docs/basics/cd.md new file mode 100644 index 00000000..c54653a8 --- /dev/null +++ b/docs/basics/cd.md @@ -0,0 +1,16 @@ +--- +hide: + - toc +--- + +MiSTer supports Cue/Bin and [CHD](https://github.com/rtissera/libchdr){target=_blank} formats. The way the MiSTer handles CD-based ROMs and images is fairly simple. There are some specifics that need to be described about how the MiSTer handles CDs. + +## Will MiSTer ever support USB CD Drives? + +The short answer is **no**. The long answer is that 1) there is too much hardware variation in CD drives and the drivers that go with them for it to be worth it and 2) everything added to the Linux image and Main binary for the MiSTer have to be very carefully considered as the goal is to keep it lightweight and not bloated. + +CD Drive support is not a priority, as properly dumped CD-ROM images are bit-perfect where it counts (excluding randomized subchannel data and garbage data fill-in). + +## Cue/Bin Folders and CHD files + +If you are using cue/bin files, then you need to place them in their own folder separate from the other cue/bin ROMs. Currently every CD-based core supports cue/bin. CHD files are a compressed CD image format that is also supported by almost every CD-based core. CHD files don't need to be placed in their own folder separate from each other. diff --git a/docs/basics/faq.md b/docs/basics/faq.md new file mode 100644 index 00000000..6992cd58 --- /dev/null +++ b/docs/basics/faq.md @@ -0,0 +1,145 @@ +Here are some Frequently Asked Questions that you may have. If there is anything missing here, feel free to contribute by editing the page on github using the Edit pen icon in the top right. + +## When will MiSTer support cartridges? +MiSTer will never use physical cartridges. + +The project aims to replace the need for having original hardware for the same experience. It is also physically impractical/impossible given the number of GPIO pins available from the FPGA. + +## Does MiSTer have lag? +It depends on your setup, but it ranges from imperceptibly low to around one frame of lag. + +Zero latency is possible with certain equipment and tweaks. [See here](../advanced/lag.md) for a more detailed explanation. + +## I've seen in the news, "Update Framework". What does that mean? +The 'framework' is all the common elements between cores that handle things like IO, video scaling, etc. + +## Can I use original console controllers? +Yes, there are many USB adapters for original console controllers. They can also be connected directly via the IO board as detailed below. + +## What about light guns? +Light guns such as the NES Zapper are too timing sensitive to work over USB, but will work fine on supported cores via the IO board as detailed below. + +## Any USB controller recommendations? +Almost any controller that uses USB will work with MiSTer. You can also use a Bluetooth or 2.4ghz USB adapter for wireless. Good controllers that many users seem to like and have low input latency are: + +* [Sony DualSense (PS5 Controller)](https://www.playstation.com/en-us/accessories/dualsense-wireless-controller/){target=_blank} - Very low lag, fast pairing, touchpad, and extra button (mute) if paired with a bluetooth 5.0 adapter (TP-Link UB-500, Edimax BT-8500, or Asus USB-BT500 adapters are recommended and known to work). +* [8BitDo M30 Bluetooth](https://www.8bitdo.com/m30/){target=_blank} and [8BitDoM30 2.4G](https://www.8bitdo.com/m30-2-4g-for-genesis-mini-mega-drive-mini/){target=_blank} - Note these kinds of controllers do not have as many buttons as the Playstation style controllers and you may be limited if you use them. +* [8bitDo SN30 Pro 2](https://www.8bitdo.com/pro2/){target=_blank} - Versatile connectivity and confortable design that is similar to the Playstation DualShock form factor with an SNES aesthetic and button layout. +* [8bitDo Arcade Stick](https://www.8bitdo.com/arcade-stick/){target=_blank} - Wired and wireless low lag functionality with low variable lag, customizable buttons and joystick is supported. +* [iBuffalo SNES Controller](https://www.amazon.com/Buffalo-iBuffalo-Classic-USB-Gamepad/dp/B002B9XB0E/){target=_blank} - A little overpriced now, but it is a very low lag controller. + +And many many more. Check [MiSTerAddons' input latency tests](https://rpubs.com/misteraddons/inputlatency){target=_blank} to help you decide. Also to ensure you get the fastest response make sure to check the [USB overclock instructions](../advanced/lag.md) section out. + +There are also some excellent usb controller adapters which enable you to use original console controllers: + +* [Timville Triple Controller Daemonbite](https://www.tindie.com/products/timville/triple-controller-classic-gaming-usb-adapter/){target=_blank} - A spinoff of MickGuyver's Daemonbite adapters that has support for NES, Genesis, and SNES original hardware. You can also make it yourself using instructions found [here](https://github.com/timville85/TripleController){target=_blank}. There is an option to purchase a 3d printed housing that you can also print yourself using the 3d files from [here](https://www.thingiverse.com/thing:5011783){target=_blank}. +* [MickGuyver's Daemonbite adapters](https://www.daemonbite.com/shop/){target=_blank} - Very low latency adapters, often low supply and sold out however. Can build them yourself using instructions found [here](https://github.com/MickGyver/DaemonBite-Arcade-Encoder){target=_blank} and [here](https://github.com/MickGyver/DaemonBite-Arcade-Encoder){target=_blank}. +* [2600-daptor D9](http://www.2600-daptor.com/){target=_blank} - Lowest latency "controller" in the [MiSTerAddons input latency tests](https://rpubs.com/misteraddons/inputlatency){target=_blank}. + +## Can I increase the polling rate of my USB controller to improve input latency? +Yes, you can. [See here](../advanced/lag.md). + +## Do I need the official USB Hub Add-On Board? +No, but you will probably want some sort of inexpensive OTG hub at least (or a regular hub with an adapter). Use a powered hub if you have many devices. + +## Do I need to have a USB keyboard with me to use MiSTer? +Yes, it's a good idea to always have a USB keyboard available. Cheap wireless keyboards exist that you can use to reduce clutter. + +## How do I add a second controller to MiSTer? +First setup the controller in the main menu after plugging it in with no core loaded. Then you can define it in the various cores' OSD menus. + +## Does MiSTer need an IO board? +No. The IO board is optional, but offers features that could be important for some users (3.5mm and optical audio, CRT output, tape audio input, etc). + +## What are the methods for connecting controllers to the serial port of the IO add-on board? +SNAC (Serial Native Accessory Converter) is used for direct wiring. Supporting cores (SNES, Genesis, NES, and TG16) allow you to directly connect original controllers. See [this page](https://github.com/blue212/SNAC){target=_blank} for details on SNAC. + +## Do I need an IO board to get analog video output to my CRT? +No. You can use an HDMI to VGA adapter to do it instead. See [Direct Video](../advanced/directvideo.md). + +## Is MiSTer hard to set up? Is it really only for technical people who like to tinker? +No and no, but those who enjoy tinkering can get a lot extra out of their MiSTer if they wish. The minimum setup only requires attaching a memory board to a DE-10 Nano and making an SD card. See [the Setup Guide](../setup/requirements.md) for more information. + +## Which cores require SDRAM? +You can find the updated list at the [Console Cores](../cores/console.md) and [Computer Cores](../cores/computer.md) sections. Many Arcade cores use SDRAM as well. + +## Why does the NES core require an SDRAM add-on board when the Genesis core does not? +The Genesis has graphics RAM and stores data that is copied from the cartridge ROM. The NES does not do this, and typically accesses the ROM directly for the data which requires much tighter timings. Using the SDRAM board on the NES core allows meeting these timing requirements. + +## Does my MiSTer need cooling? +Yes, you will want at least a heatsink (passive cooling). 22mm x 22mm is the ideal size. Active cooling (a fan) helps but is not strictly required. Some faster cores like ao486 may generate a lot of heat. + +## What power supply is compatible with MiSTer? +The DE10-Nano board needs a 5V power supply with at least 2A. The connector is a coaxial "barrel" plug of 5.5 mm outer diameter and 2.1 mm inner diameter, center positive. If you are using a USB Hub addon board and have a lot of power hungry peripherals attached to it (wifi, bluetooth, multiple controllers), it might be a good idea to upgrade to a similar 5v power supply, but with more amps (4A-5A). + +## My MiSTer needs a case. What should I do? +There are two routes you can take; either make it yourself or purchase a case from an online vendor. For DiY, you can find the necessary 3D print files online (e.g. [thingiverse](https://www.thingiverse.com/search?q=mister+fpga){target=_blank}). + +## What kind of screws do I use with the DE-10 Nano's 14mm long brass standoffs? +M3 screws, 8mm is a good length. + +## How do I set up MiSTer for 1080p, shimmer free gameplay? +Run the updater script and use one of the video presets + filters that come with it in the Video Processing menu on the secondary OSD. See [Video Configuration](video.md) for more specific information. + +## How do I get the scanlines filters on my MiSTer to look good? +You will need to set the device to integer scaling for best results. Either set vscale_mode=1 in mister.ini or use the vscale integer settings within the core itself (as well as 5x) if they are supported. Not all cores support the OSD options to do integer scaling. + +"Integer scaling" is when your source resolution (240p) is divided into your target resolution (1080p) using only whole numbers (e.g. 1, 2, 3, 4...). This means if you use integer scaling with the MiSTer set to a 1080p resolution in the MiSTer.ini, and the core you are using natively outputs 240p, then the image will be scaled 4x which 4 times 240 equals 960. This leaves a black border for the remaining 80 pixels distributed across the top and bottom the screen. + +You can play with other settings if you want the scaler to fill the screen, but scanlines won't be "perfect" unless the source resolution (e.g. 240p) divides evenly into the target resolution (e.g. 1200p at 5x scaling). + +## I have a 4k or other higher than 1080p display, does MiSTer support that resolution? I'd like to enjoy better video scaling. +MiSTer can't quite reach 4k. Edit mister.ini on your SD card to change resolutions, e.g. video_mode=12 for 1440p or video_mode=13 for 1536p (hardware maximum). Compatibility with these higher resolutions may depend upon your display and signal chain. + +## How does the accuracy level of various MiSTer cores compare to other FPGA options? +Most MiSTer cores are just as, if not more accurate, as any of the other major FPGA offerings available today. Most people would not able to tell the difference between these cores and the original hardware. + +## Will any MiSTer core ever get save states? +The Gameboy, GBA, Lynx, and NES core supports save states. + +Cores need to be written from scratch to support them (as was done with the GBA and Lynx cores) or they need to be reworked to support pause before save states can be added (as was done with the Gameboy and NES cores). At this time there are no specific plans to apply this to other cores, but it may happen one day. + +## Why doesn’t this core from another repo work? Why is MiSTer so hard to use? +MiSTer repositories are self contained and the official updater script only fetches cores from the active official MiSTer repositories. Cores from other repos are not fully integrated so your results may vary. Some developers have their own discord servers or forums and you can seek support there. + +## When is an N64 core coming? +Probably never. There isn’t really sufficient bandwidth. + +## When is PlayStation core coming? +Probably next year. Serious progress has been made by a few developers but there’s no official ETA. + +## Other cores work but I get a black screen for this one. What do I do? +Try setting vsync to 0 as your display may not support all refresh rates. (Note that this was the default setting.) + +## My CD games don’t work! Help! +Unzip them. Do not zip CD games. Also put them in iso/wav/bin/img + cue format. + +## What version of the CD card bios do I need for TG16 CD? +Use Japanese version 3.0. You will commonly find it with filename: `Super CD-ROM System (Japan) (v3.0).pce` + +## How do I make MisTer boot into the NES core and a specific game? +You need to use two different options: autobooting a core, and starting the core on a given ROM. Here is how: +In the .INI file, set `bootcore=NES_20201102.rbf` (or the specific core version you have), and comment out `;bootcore_timeout`. +Then on your NES games folder (e.g. `/media/fat/games/NES/`, copy the FDS bios as `boot0.rom`, and your .NES rom to boot as `boot1.rom`. +For more options, please refer to the [NES core documentation](https://github.com/MiSTer-devel/NES_MiSTer#installation){target=_blank} + +## I heard the DE10-Nano board uses subsidized components. Is MiSTer doomed if that stops? +De10-Nano is manufactured in very large scale for use by students and is widely available. When it reaches end of life, the open source cores and infrastructure will be ported to another widely available board. + +## I see a defect that some other people aren’t seeing. Should I get a different DE-10 Nano? +No, you should report the defect and wait for a fix. There is no magical best DE-10 Nano. + +## I found some other Cyclone based dev board on sale and it has built in WiFi. Can I use it for MiSTer? +Generally, no. While it’s always possible that someone will take time to port things to other boards, the different pins and memory will mean it won’t be a straight use and unless it’s a significant upgrade, it would never gain official support. + +## The DE-10 is rated for up to 100°C operation and it doesn’t get nearly that hot. Do I really need a fan or heatsink? +A number of complex cores (like ao486) benefit from having the chip at cooler temperatures, since heat can affect the tight timings they require. A fan is recommended to avoid any possible glitches, but you won't damage your DE10-Nano if you choose not to use one. + +## Can you take screenshots on the MiSTer? +You can take screenshots on the MiSTer very easily. All you have to do is press `Win + PrtScr` on your keyboard and you will get an upscaled screenshot. For raw output from the core (which may be distorted or in a weird aspect ratio) prese `Shift + Win + PrtScr`. The screenshots are stored in `./screenshots` in a folder named after the core you took the screenshot in. + +These screenshots do include the effects of any video processing options, they are very simple. To take screenshots of the full video processing (i.e. the image you see on your modern screen when using the MiSTer) you will need to use some kind of capture card that supports the desired resolution. + +[Here is an example of a raw screenshot from the NES core](img/raw_screenshot.png){target=_blank} + +[Here is an example of an upscaled screenshot from the Neo Geo core](img/upscaled_screenshot.png){target=_blank} diff --git a/docs/basics/hotkey.md b/docs/basics/hotkey.md new file mode 100644 index 00000000..29815ba2 --- /dev/null +++ b/docs/basics/hotkey.md @@ -0,0 +1,44 @@ +--- +hide: + - toc +--- + +Here's a reference of the hotkeys you can use with the MiSTer. Hotkeys are useful at saving time and there are some hotkeys which do things you can only do with a keyboard or gamepad. Some of these hotkeys only work in the Main Menu core, others will work inside emulators as part of the gameplay, and some will work in all instances. + +## In any core, with OSD closed + +| Hotkey | Description | +| ----------------------------------------- | ---------------------------------------------------------------------------------- | +| F12 | Open or close the Menu/On-Screen Display | +| Alt + F12 | Open core select menu | +| Win + PrtScr | Take a screenshot (upscaled) | +| Shift + Win + PrtScr | Take a screenshot (raw output) | +| LeftCtrl + LeftAlt + RightAlt | Press "User" button, usually resets current core, same function as IO board button | +| LeftShift + LeftCtrl + LeftAlt + RightAlt | Full Reboot/Reset, same as IO add-on board Reset button | +| Controller: Button + OSD button | Turn on/off turbo/autofire for the pressed button | +| Controller: Direction + OSD Button | Set rate of turbo/autofire in milliseconds (ms) | + +## With the OSD open, in any core + +| Hotkey | Description | +| -------------------------- | ----------------------------------------------------------------------- | +| F12 | close OSD | +| F11 | Pair Bluetooth controller | +| Left | Go to information screen (shows currently selected INI file and volume) | +| Right | System screen (change core, set filters, gamma, etc...) | +| Controller: Back + R/L/D/U | Select Alternate INI file if defined (Default/Alt1/Alt2/Alt3) | +| Controller: Select | Expands submenus in the OSD when highlighted | + +## In the Main Menu core only + +| Hotkey | Description | +| ------ | ------------------------------------------------------------------------ | +| F1 | Switch background type (static, wallpaper, color bars, black) | +| F2 | Hide / Show core dates | +| F9 | Open Linux terminal / command line interface, use F12 to go back to menu | + +## Core-specific hotkeys + +| Core | Hotkey | Description | +| ----- | --------- | ------------ | +| ao486 | Win + F12 | Open the OSD | diff --git a/docs/basics/img/5x-vertical-crop.png b/docs/basics/img/5x-vertical-crop.png new file mode 100644 index 00000000..09376aa7 Binary files /dev/null and b/docs/basics/img/5x-vertical-crop.png differ diff --git a/docs/basics/img/default-video-nes.png b/docs/basics/img/default-video-nes.png new file mode 100644 index 00000000..75fd9d72 Binary files /dev/null and b/docs/basics/img/default-video-nes.png differ diff --git a/docs/basics/img/gamma-curve.png b/docs/basics/img/gamma-curve.png new file mode 100644 index 00000000..4280b3b9 Binary files /dev/null and b/docs/basics/img/gamma-curve.png differ diff --git a/docs/basics/img/horz-filter.png b/docs/basics/img/horz-filter.png new file mode 100644 index 00000000..dac0345f Binary files /dev/null and b/docs/basics/img/horz-filter.png differ diff --git a/docs/basics/img/interpolation-medium.png b/docs/basics/img/interpolation-medium.png new file mode 100644 index 00000000..ac44422f Binary files /dev/null and b/docs/basics/img/interpolation-medium.png differ diff --git a/docs/basics/img/pure_gamma-gamma_113.png b/docs/basics/img/pure_gamma-gamma_113.png new file mode 100644 index 00000000..3e39dd05 Binary files /dev/null and b/docs/basics/img/pure_gamma-gamma_113.png differ diff --git a/docs/basics/img/raw_screenshot.png b/docs/basics/img/raw_screenshot.png new file mode 100644 index 00000000..b03c3390 Binary files /dev/null and b/docs/basics/img/raw_screenshot.png differ diff --git a/docs/basics/img/scanlines-brighter.png b/docs/basics/img/scanlines-brighter.png new file mode 100644 index 00000000..f5d528f8 Binary files /dev/null and b/docs/basics/img/scanlines-brighter.png differ diff --git a/docs/basics/img/squished-vga-bright-v2.png b/docs/basics/img/squished-vga-bright-v2.png new file mode 100644 index 00000000..142ec553 Binary files /dev/null and b/docs/basics/img/squished-vga-bright-v2.png differ diff --git a/docs/basics/img/upscaled_screenshot.png b/docs/basics/img/upscaled_screenshot.png new file mode 100644 index 00000000..12235984 Binary files /dev/null and b/docs/basics/img/upscaled_screenshot.png differ diff --git a/docs/basics/img/video-processing.png b/docs/basics/img/video-processing.png new file mode 100644 index 00000000..d87550e0 Binary files /dev/null and b/docs/basics/img/video-processing.png differ diff --git a/docs/basics/input.md b/docs/basics/input.md new file mode 100644 index 00000000..b3b82ae1 --- /dev/null +++ b/docs/basics/input.md @@ -0,0 +1,43 @@ +--- +hide: + - toc +--- + +MiSTer has support for a wide variety of input devices. It also has options to configure these devices to fit your needs. Here is a breakdown of some special configurations for various input devices like spinners, gamepads, joysticks, and keyboards. + +## What is supported? + +Generally speaking, any normal USB HID compatible input device should work. Keyboards, arcade spinners, usb adapters for original controllers such as the Raphnet and Daemonbite retro adapters, and even modern console controllers like the DualSense PS5 controller. There is even the Serial Native Accessory Connector, if you have one of the Analog or Digital IO add-on boards, which on supported cores allows you to use original hardware controllers, such as lightguns, which would normally only work with the original system and require zero lag to function. + +## Serial Native Accessory Convertor (SNAC) + +SNAC adaptors allow you to connect original hardware controllers and peripherals to the MiSTer cores. The cores which support SNAC connections have been specially built to have serial connections exposed to specific pins on the DE10-Nano. That means when you pull the trigger on the NES Zapper while aiming at your CRT, the signals travel almost instantly, similar to how they would on original hardware. + +## Using A Mouse + +You can also use a mouse for various purposes on the MiSTer. The main purpose for mouse support is for use with some computer cores which had mice. + +One of the cool things you can do is use the mouse as an emulated lightgun. The same principles behind doing this applies to a wiimote with a powered sensor bar. You can do this by pairing your wiimote to the MiSTer and it will be used as a Mouse when paired. + +![type:video](videos/mouse-lightgun.mp4) + +You can also use a mouse for a paddle style controller if you'd like. + +## Are gaming keyboards worth it? + +High performance and expensive keyboards and mice aren't advantageous to use for MiSTer. They won't give any major or even minor significant benefits. Additionally, these devices often have too many functions and many virtual devices cluttering the input subsystem which may introduce input lag or be complete unresponsive. They may also prevent other devices, such as gamepads, from working. So if you experience problems with your gaming keyboard, try a simpler keyboard instead to see if that resolves the issue. General advice is not to go out and buy a specialty gaming keyboard for MiSTer specifically, it may end up being a waste of money. + +## What about rumble support? +Currently rumble support is not added into the framework. It will maybe come at a later time, but some cores do have the support built into them (GBA, etc...)so they are ready for when it is added. + +## What about PS3/PS4/PS5, XBoxOne/360, Switch, and 8bitdo receivers/gamepads? +The ideal solution today for these types gamepads is to use 3rd-party receivers, such as 8bitdo retro receivers, specifically the 8Bitdo Wireless Bluetooth Adapter, or any number of name-brand Bluetooth 4.x/5.0 receivers. The 8bitdo receiver easily supports Xbox One S/X, PS3, PS4, Wii, Switch, and 8Bitdo's own gamepads and it can pair easily without using the bluetooth setup menu. One 8bitdo bluetooth receiver will pair with one controller at one time. If multiple controllers are required for multiplayer games, then multiple receivers will need to be purchased if you are using the 8bitdo receiver, however a regular Bluetooth usb receiver does not suffer from this limitation. + +The 8bitdo receivers have been reported as having some lag introduced, limited range, and bad line of sight, when compared to Bluetooth 5.0 adapters (like the TP-Link and Asus ones). The main appeal of the 8bitdo receivers is the ease of use and quick pairing. The 8bitdo receivers act as a controller themselves and are a compatibility layer between your paired controller and whatever they are attached to via USB, for easy compatibility. Bluetooth adapters by comparison pair your controller itself directly as a device to the MiSTer. No matter what controller you connect, the 8bitdo receiver will see it as the same controller, the 8bitdo receiver's controller. This means that some features like the DualSense (PS5) controller's added mute button and touchpad will not be available, whereas using bluetooth 5.0 may run a very minor risk of limited compatibility (until device support is added into the framework and linux by the development team), but will come with every feature. + +The Grey/Orange (brick decorated) USB Adapters are functionally the same, after using the latest firmware. Gamepads may switch to different input modes using hotkeys for different functionality (depends upon the model of controller, some have a switch on the back like the 8bitdo SN30 Pro 2). Note that documentation on 8Bitdo's site doesn't specify this, but the update logs for the firmware updates does. + +* X-Input mode: Hold SELECT+UP for 3 seconds. +* PSC (Playstation Classic) mode: Hold SELECT+DOWN for 3 seconds. This is useful for gamepads which are limited in buttons (12 total; DPAD counts as 4) and need to access the MiSTer OSD menu. Note that the OSD menu should not be assigned when configuring buttons in the main MiSTer menu core, as the L+R+START combination will bring up the OSD while in the cores. The combination is hard-coded in MiSTer specifically for 8Bitdo adapters. You may also lose auto-fire/mouse functionality in this mode. + +Alternative 8Bitdo adapters, such as the 8Bitdo Console Retro Receiver (SNES, NES, Genesis) are always in X-Input mode when connected via microUSB. diff --git a/docs/basics/keyboard.md b/docs/basics/keyboard.md new file mode 100644 index 00000000..53b2a3f8 --- /dev/null +++ b/docs/basics/keyboard.md @@ -0,0 +1,32 @@ +--- +hide: + - toc +--- + +MiSTer supports keyboard re-mapping which is useful for reduced size or localized keyboards. Key remapping is system wide, so every core will have same key mapping. Keep in mind there is no macro key functionality, so single keys are remapped to another single key. Some multimedia keys generate several [key codes](https://www.scs.stanford.edu/10wi-cs140/pintos/specs/kbd/scancodes-5.html){target=_blank} - these keys cannot be remapped. Each keyboard model has its own key map stored in `/media/fat/config/kbd_[VID]_[PID].map` file. To reset all keys to their default state, simply delete the appropriate map file which has the matching VenderID and ProductID in the filename. Key remapping is available through the Menu core only. + +## Joystick emulation +Keyboards can be switched to joystick emulation. You need to define keys used for joystick emulation the same way you did for joysticks. Auto fire is also supported the same way as they are for joysticks (Menu+button). The button defined for "KBD TOGGLE" provides a quick switch between keyboard and joystick use for defined keys. + +## Mouse emulation +Keyboards can be switched to mouse emulation. You need to define mouse emulation buttons in the Menu core the same way as for joystick, in the Define Gamepad menu option. + +## Emulation switch +To switch between emulation modes press `NumLock` or `ScrLock` until the desired mode is selected. + +The switching sequence is `Mouse >> Joy1 >> Joy2 >> None` + +The LEDs on your keyboard will display the emulation modes: +* Mouse emulation: NumLock LED + ScrLock LED +* Joystick 1 emulation: NumLock LED. +* Joystick 2 emulation: ScrLock LED. + +## Common functional keys/combos used in cores +* `F12` - open/close OSD menu/submenu +* `Alt-F12` - quick core selection (like in Menu core). +* `LCtrl+LAlt+RAlt` - presses the "USER" button which usually is reset in emulated system. +* `LShift+LCtrl+LAlt+RAlt` - MiSTer reset (load Menu core). + +### Notes: +* Some systems provide writing support which requires additional attention to how you reset/shutdown the MiSTer. MiSTer tries not to keep any pending writes and writes physically to the disk as soon as possible. Still, safer way to reset the MiSTer from core which probably was writing to disk recently is using combo `LShift+LCtrl+LAlt+RAlt` - this will flush all caches to disk before restart. Cores without write can be restarted by hard reset button or powered down without special attention. +* `LCtrl+LAlt+RAlt` sequence can be replaced by some other well known combos through INI file. diff --git a/docs/basics/links.md b/docs/basics/links.md new file mode 100644 index 00000000..d7b81b61 --- /dev/null +++ b/docs/basics/links.md @@ -0,0 +1,48 @@ +--- +hide: + - toc +--- + +Here's a collection of links to various information, videos, and articles about the MiSTer. MiSTer is an evolving platform, so these videos can only represent what was available at the time of them being made, some information and representations may be outdated. + +## MiSTer FPGA Articles +* [Polygon - MiSTer 101: A classic gaming device to rule them all by Christopher Grant](https://www.polygon.com/22640171/mister-project-classic-gaming-retro-fpga-board-chip-io-explainer-usb-hub){target=_blank} - August 8, 2021 +* [Kotaku - And Now, The Ultimate Retro Gaming Device by Mike Fahey](https://kotaku.com/and-now-the-ultimate-retro-gaming-device-1847608362){target=_blank} - September 02, 2021 +* [Edge Magazine Australia - Hard Core: How MiSTer emulation is redefining the art of resurrecting gaming's past by Alex Wiltshire](https://www.pressreader.com/australia/edge/20210422/284249533161844){target=_blank} - April 22, 2021 +* [The Verge - The DIY Issue: Building The Ultimate Retro Computer by Sam Byford](https://www.theverge.com/22323002/mister-fpga-project-retro-computer-console-early-pc){target=_blank} - March 11, 2021 +* [Nintendo Life - Hardware Review: MiSTer FPGA - A Tantalizing Glimpse Into The Future of Retro Gaming by Damien McFerran](https://www.nintendolife.com/news/2021/02/hardware_review_mister_fpga_-_a_tantalising_glimpse_into_the_future_of_retro_gaming){target=_blank} - February 11, 2021 +* [Dream Machine: MiSTer FPGA by Félix Léger (@felleg)](https://felixleger.com/posts/2020/10/dream-machine-mister-fpga/){target=_blank} - October 18, 2020 + +## Tutorials/Guides +* [MiSTer Manual by adreeve](https://github.com/adreeve/MiSTerManual){target=_blank} + +## MiSTer FPGA Videos + +* [Jan 2021 - Digital Foundry - DF Retro Hardware: MiSTer FPGA - A Brilliant Mini Emulation System Explored!](https://www.youtube.com/watch?v=PfIwDC2F2lc){target=_blank} +* [Jan 2021 - Scarlet Sprites - MiSTer FPGA Review 2021: Arcade & Console Accuracy!](https://www.youtube.com/watch?v=wxkBDK-99mY){target=_blank} +* [Dec 2020 - Retro Bits - MiSTer FPGA - how to build, demo, costs, and pro/cons](https://www.youtube.com/watch?v=-IP0k3GatHE){target=_blank} +* [Mar 2020 - Briar Rabbit - What is a MiSTer FPGA?](https://www.youtube.com/watch?v=lJZwMUaJmc0){target=_blank} +* [Nov 2019 - SmokeMonster - MiSTer Cores without add-ons (no SDRAM)](https://www.youtube.com/watch?v=_g471imXA7U){target=_blank} +* [Jul 2019 - RetroManCave - Exploring MiSTer](https://www.youtube.com/watch?v=e5yPbzD-W-I){target=_blank} +* [May 2019 - GameSack - MiSTer Review](https://www.youtube.com/watch?v=dibLXWdX5-M){target=_blank} +* [Oct 2018 - ETA Prime - FPGA Emulation MisTer Project on the Terasic DE10-Nano](https://www.youtube.com/watch?v=1jb8YPXc8DA){target=_blank} +* [Oct 2018 - SmokeMonster - Introducing the MiSTer FPGA](https://www.youtube.com/watch?v=igiVHfBzX8w){target=_blank} + +## Tutorials + +* [MiSTer assembly and config (Ownlonymous)](https://www.youtube.com/watch?v=9CGZtv7vj5A){target=_blank} +* [Creating a MiSTer SD card (NML32)](https://www.youtube.com/watch?v=lPObjJvPeW0){target=_blank} +* [Mounting a VHD from Windows over the network (NML32)](https://www.youtube.com/watch?v=OR0wVkt3kY8){target=_blank} +* [MiSTer FPGA How To Setup Tutorial (MadLittlePixel)](https://www.youtube.com/watch?v=OkQJ0Vc75AE){target=_blank} +* [MiSTer FPGA Input Mapping (rsn8887)](https://www.youtube.com/watch?v=8tGPDTcuDSE){target=_blank} +* [MiSTer FPGA Getting Started and Setting up with Mr. Fusion (Master Hacks)](https://www.youtube.com/watch?v=1EMz1a87FO0){target=_blank} +* [AO486 Core - Setting up DOS Games with pre-built Total DOS Launcher (FlynssBit)](https://www.youtube.com/watch?v=rLpAUtALJfw){target=_blank} + +## FPGA Discussion + +* [Oct 2019 - Lon.TV - Lon & RetroRGB discuss FPGA](https://www.youtube.com/watch?v=NJtwaHeGmrk){target=_blank} +* [Sep 2019 - SmokeMonster - FPGA Revolution](https://www.youtube.com/watch?v=X2G0WJ-Z9tk){target=_blank} + +## Other / Demonstrations +* [Jul 2020 - RetroManCave - My Ultimate FPGA Desktop](https://www.youtube.com/watch?v=TCQuUwHH45w){target=_blank} + diff --git a/docs/basics/video.md b/docs/basics/video.md new file mode 100644 index 00000000..c06a3148 --- /dev/null +++ b/docs/basics/video.md @@ -0,0 +1,123 @@ +Here's a description of some basic video customization features on the MiSTer. You can change your resolution, modify the framebuffer to reduce input latency and video stuttering, add some video filters, use shadowmasks, and even gamma correction. Also, you can use 5x overscan mode to push a 1200p image into 1080p for square pixels and nearly the original overscan of a CRT, depending on the game's resolution. There are lots of options to play with, here's some basic ones. + +## MiSTer Ini Video Settings +In the [MiSTer.ini](../advanced/ini.md){target=_blank} file there are many video setttings to try. We'll just focus on a couple here for now and you can dive deeper into things like CRT usage in the [Advanced - CRT](../advanced/crt.md){target=_blank} section. + +First, you can edit the settings in the `MiSTer.ini` file with windows Notepad, Visual Studio Code, Notepad++. Pretty much any text editor will be fine. Alternatively you can run the `ini-settings.sh` script in the scripts folder, this has a simple interface to change options. + +### video_mode +A bit of a ways down the .ini file there is a `video_mode` option. Above it the resolutions are commented: + +``` +; 0 - 1280x720@60 +; 1 - 1024x768@60 +; 2 - 720x480@60 +; 3 - 720x576@50 +; 4 - 1280x1024@60 +; 5 - 800x600@60 +; 6 - 640x480@60 +; 7 - 1280x720@50 +; 8 - 1920x1080@60 +; 9 - 1920x1080@50 +;10 - 1366x768@60 +;11 - 1024x600@60 +;12 - 1920x1440@60 +;13 - 2048x1536@60 +``` + +This tells you that `video_mode=0` will set you to 1280x720 resolution at 60hz. For most people they will probably want to use 1920x1080 resolutiono at 60hz, so my advice would be to change this to `video_mode=8`. You can also use the `ini-settings.sh` script, it will tell you what option selects which resolution, so just select the right one for your display. + +### vsync_adjust +Another important option is `vsync_adjust`. Most modern displays work fine at 60hz, but some games run at 60.6 hz (like Donkey Kong for the arcades) which is a "non-standard refresh rate". Therefore, MiSTer has what is called a "framebuffer". The game is still running at 60.6hz but the frames are sent at 60hz. So occasionally there is a little "stutter" on the screen to make up for the frames going too fast and being adjusted. To use a framebuffer adds a minimal amount of lag. Here's a list of the options and what they do. + +```ini +vsync_adjust=0 +``` +This matches the refresh rate of your monitor (e.g. 60hz) and has about 1-2 frames of lag. Video output can be a little jittery as the core is still running at it's native rate, which isn't exactly 60hz. +```ini +vsync_adjust=1 +``` +This makes the video output at exactly the frame rate of the game (e.g. 60.6hz). It has 1 frame of lag, but it is less compatible with modern televisions. Video output is very smooth. +```ini +vsync_adjust=2 +``` +This makes the video output draw to the screen as fast as possible, and can result in sub-frame lag consistently (independent of your controller and display's built-in lag). However this is the least compatible mode and it may result in unplayable behavior on some televisions using certain cores. The video output is the very smooth. Additionally, because of the way this special mode works there is a mismatch in the refresh rate of the scaled output and the core's original video output. + +Generally speaking, the rule of thumb is that if you want the smoothest video output and lowest lag then start at `vsync_adjust=2` and if a core doesn't work that you want to play on reduce it to 1 or 0 to see if the compatibility is resolved. Your results may vary depending on the display you are connected to and what core you are using. + +### Core exceptions +There are also ways to add exceptions. My monitor doesn't play nice with the low lag setting on the Genesis core. So in my MiSter.ini, I added the following override/exception to the **end of the file** for just the MiSTer core: + +```ini +[Genesis] +vsync_adjust=0 +``` + +This makes it so no matter what my `vsync_adjust` setting is in the upper section, when I use the Genesis core, it will force it to use `vsync_adjust=0` (the most compatible mode) every time. + +## Video Processing Options Tutorial +Here's a tutorial that you can follow along to get you started using the powerful video processing options on MiSTer FPGA. +### Filters (and scanlines) +MiSTer has the capability to use upscaling filters and scanlines to help enhance the video output or even make it feel similar to a retro CRT television. If you opened the NES core for the first time after setting the MiSter's video output to 1920x1080p and loaded up Duck Tales, then you should see something like this: + +[![Duck Tales NES MiSTer FPGA 1920x1080@60 Default Video Output](img/default-video-nes.png)](img/default-video-nes.png){target=_blank} + +This can be tweaked a little to make it look a lot nicer to our eyes. First let's go into "Video Processing" in the secondary OSD/Menu (press F12 or the menu button you assigned earlier, and then right to see the secondary menu): + +![MiSTer FPGA Video Processing options selection](img/video-processing.png) + +When you select this it will show you a screen with a bunch of options. Don't get overwhelmed, it's fairly simple when you follow this guide, and you will understand how they work. I'll give you some recommended settings for most of the cores at the end of this tutorial which should be your go-to for now while you get used to things. + +By default "Video Filter:" is set to "NearNeighbour". This is a nearest neighbour filter. Basically, to turn 240p video into 1080p video requires these pixels to be made larger. Since 240 doesn't divide evenly into 1080 (1080 / 240 = 4.5), then some of these pixels won't be perfectly square. Nearest neighbour helps fool your eyes into making them seem more square than they actually are. It's filtering the video before it reaches your eyes to make it look better! + +Select Video filter to change it so you can select a filters file. You will notice the text changes from `Video Filter:` to `Horz filter:`. Don't worry about this too much, for any normal rotation games, Horz is for your upscaling filters that soften or sharpen the image. + +Select the `` below to browse. It should show you quite a few options. For now select `Interpolation (Medium).txt`. This is a filter which gives you some softer edges while still maintaining an illusion of square pixels. + +![MiSTer FPGA Horizontal Interpolation filter horz filter:](img/horz-filter.png) + +There we go, those pixels are a bit smoother now: + +[![Mister FPGA Horizontal Interpolation Medium filter horz filter: NES duck tales](img/interpolation-medium.png)](img/interpolation-medium.png){target=_blank} + +Another added benefit to interpolation is the scrolling looks smoother to the eye when compared to sharper filters like the default Nearest Neighbour setting. + +Now let's say you want some scanlines, sorta like what CRT's had and some emulators have an option for. Well to do that, we just need to setup the `Vert Filter:` option like we did the horz filter. You see, we will be filtering horizontal lines from top to bottom (vertically) on the video output. Inside `Vert Filter`'s `From File` option, select `Scanlines - Brighter.txt`. You should see something like this as your options: + +[![MiSTer FPGA's Vertical filter Scanlines - Brighter vert filter](img/scanlines-brighter.png)](img/scanlines-brighter.png){target=_blank} + +### 5x Vertical Crop (1080p only) +**Note: this feature only works if your output resolution in your MiSTer.ini is set to a 1080p option!!** + +If you have been following along on your MiSTer, you might notice that the scanlines look darker occasionally. This is because 240p (this game's resolution) doesn't divide equally into 1080p (your resolution on your MiSTer). But 240 does divide into 1200 equally, 5 times 240 equals 1200. So to fix these scanlines looking uneven, we can stretch the image vertically to make all the pixels perfectly square. Go back into the regular core menu and select `Video & Audio`. There is an option called `Vertical Crop`. Not all cores have this, but the NES core does happen to, so it's a good example. Go ahead and select the `Vertical Crop` option to change `Disabled` to `(216p)5X`. + +[![MiSTer FPGA Vertical Crop 5x mode 1080p to 1200p 216p to 5x with overscan](img/5x-vertical-crop.png)](img/5x-vertical-crop.png){target=_blank} + +You will see just a few lines off the top and bottom get cut off. This is okay, original CRT's cut off about the same amount from the top and bottom anyways. Most games don't have information missing at the edge of the top and bottom. + +Now your `vert filter: scanlines - brighter.txt` option should have evenly spaced scanlines vertically, and the image will look a lot better. + +### Shadowmasks +MiSTer FPGA also has another layer options available to use called `Shadowmasks`. Shadow Masks are able to modify the red, green, blue color channels to create advanced effects, such as simulating the appearance of the grille or mask on an old CRT screen or the pixel layouts of old LCD handheld consoles. There are lots of options, but we are just going to use personally one of the most versatile color shadowmasks for this tutorial, `Squished VGA Bright v2.txt`. This shadowmask attempts to resemble consumer computer monitors and some tv's which had red, green, and blue phosphors in a particular pattern. Here is a picture of the options after I've added this Shadowmask to the same game's video processing menu: + +[![MiSTer FPGA Shadowmasks / Shadow Masks Squished VGA Bright v2.txt 1200p 5x overscan to 1080p with scanlines - brighter.txt](img/squished-vga-bright-v2.png)](img/squished-vga-bright-v2.png){target=_blank} + +### Gamma Curves +Gamma is a bit of a tricky thing to explain. Basically, gamma on an old CRT is the relationship between voltage and brightness. Think of a graph, the x-axis is voltage and the y-axis is the "brightness" (more accurately called luminance). Modern televisions are (ideally) a totally straight line. Old CRT's have a curve. At medium voltage and brightness it is a lot less brightness than you'd expect. Sorta like this: + +![MiSTer FPGA documentation gamma explanation graph example](img/gamma-curve.png) +[Image Source](https://www.japanistry.com/understanding-gamma-in-photography/){target=_blank} + +Now given that the MiSTer is outputting the linear example, the Gamma filters can restore a similar Gamma curve as you may have been used to with your old television. This is especially helpful because we have just applied a "brighter" scanline and a shadowmask (which added a mask of colors across the screen imitating a CRT's phosphors). If you've been following along with this tutorial so far, we're gonna play with Gamma just to see how it looks to your eyes. This is all personal preference. If it looks good to you, great. If someone else doesn't like it, well... tough! :) + +I will apply a very mild "Gamma Curve" called `gamma_113.txt` which is located in the `Pure_Gamma` folder when you select the gamma options. This gamma curve is allegedly supposed to get you close to a typical consumer CRT's gamma curve. + +[![MiSTer FPGA Gamma curve explanation with Shadow Masks Squished VGA Bright v2.txt 1200p 5x overscan to 1080p with scanlines - brighter.txt](img/pure_gamma-gamma_113.png)](img/pure_gamma-gamma_113.png){target=_blank} + +## Video demonstrations +Some people like a good video to see how it's done: +### 5x mode video +![type:video](videos/5x.mp4) + +### gamma controls video +![type:video](videos/gamma.mp4) diff --git a/docs/basics/videos/5x.mp4 b/docs/basics/videos/5x.mp4 new file mode 100644 index 00000000..367fa6fd Binary files /dev/null and b/docs/basics/videos/5x.mp4 differ diff --git a/docs/basics/videos/autosave.mp4 b/docs/basics/videos/autosave.mp4 new file mode 100644 index 00000000..861ab156 Binary files /dev/null and b/docs/basics/videos/autosave.mp4 differ diff --git a/docs/basics/videos/cheats.mp4 b/docs/basics/videos/cheats.mp4 new file mode 100644 index 00000000..23db07c5 Binary files /dev/null and b/docs/basics/videos/cheats.mp4 differ diff --git a/docs/basics/videos/gamma.mp4 b/docs/basics/videos/gamma.mp4 new file mode 100644 index 00000000..4e256bd5 Binary files /dev/null and b/docs/basics/videos/gamma.mp4 differ diff --git a/docs/basics/videos/mouse-lightgun.mp4 b/docs/basics/videos/mouse-lightgun.mp4 new file mode 100644 index 00000000..cddb831f Binary files /dev/null and b/docs/basics/videos/mouse-lightgun.mp4 differ diff --git a/docs/basics/videos/savestates.mp4 b/docs/basics/videos/savestates.mp4 new file mode 100644 index 00000000..889adc29 Binary files /dev/null and b/docs/basics/videos/savestates.mp4 differ diff --git a/docs/basics/wifi.md b/docs/basics/wifi.md new file mode 100644 index 00000000..df366823 --- /dev/null +++ b/docs/basics/wifi.md @@ -0,0 +1,42 @@ +--- +hide: + - toc +--- + +Wifi is totally optional and it's setup is fairly simple with the MiSTer. You will need a compatible dongle, the wifi script (which is provided with the Mr. Fusion image), and a keyboard attached to your MiSTer to type in your WiFi password. + +## Suggested WiFi Adapters + +You will require a compatible USB WiFi Adapter to use this feature as there is no integrated WiFi on the DE10-Nano or the MiSTer Add-on boards. Not all models of wifi adapters are compatible, so try to stick with decent name brands. Many users have found that most small ASUS, TP-Link, CanaKit, and Edimax wifi USB adapters work out of the box. Here's a few that have been reported to work: + +* ASUS USB AC53 nano rev A1 +* TP-Link AC1300 Archer T3U or Nano AC600 Archer T2U +* CanaKit Raspberry Pi WiFi dongle +* Edimax EW-7612UAn v2 or EW-7811UN or EW-7822ULC +* Netgear A6100 or A6150 + +Your results may vary as there may be new hardware revisions of these adapters which are not currently supported. There are ways to compile your own drivers for your device but that is for advanced users. **INSERT LINK TO NEW DOC FOR THIS** + +## Setup wifi with a script + +It's easy to connect to WiFi using the wifi.sh script provided with the Mr. Fusion image: + +1. Navigate to the scripts menu using the on screen display (OSD). +2. Select the "wifi" script and run it. +3. Select your WiFi network's SSID (the name of your WiFi). +4. Type your WiFi password in and press enter. +5. It should connect and ask you to press any key to continue. + +At the top of the main menu you will see a little wifi icon which indicates you have connected. This setting should be saved and it will automatically connect so long as the adapter is plugged in and your MiSTer is within range of your WiFi network. + +## The manual way to setup wifi + +In case the script isn't working for you, you can try to manually setup Wifi. This is a slightly more advanced user method so feel free to ask for help from the community before attempting this method. To manually setup WiFi without the script: + +1. Edit the file `/media/fat/linux/_wpa_supplicant.conf` with a text editor that supports Unix/Linux line endings. +2. Replace `put_your_SSID_here` with your Wifi Network's SSID, and replace `put_your_password_here` with your WiFi password. +3. Change the country code [to the one that matches your country](https://www.arubanetworks.com/techdocs/InstantWenger_Mobile/Advanced/Content/Instant%20User%20Guide%20-%20volumes/Country_Codes_List.htm){target=_blank}. +4. Rename `_wpa_supplicant.conf` to `wpa_supplicant.conf` +5. Reboot the MiSTer. + +After the MiSTer reboots you should see the wifi icon at the top of the Main Menu's OSD. This may take quite awhile so be patient, the MiSTer is not very fast at connecting to your WiFi network, it's a simple device with simple capabilities. diff --git a/docs/cores/arcade.md b/docs/cores/arcade.md new file mode 100644 index 00000000..3f160021 --- /dev/null +++ b/docs/cores/arcade.md @@ -0,0 +1,95 @@ +--- +hide: + - toc +--- + +Here is a list of the arcade cores that are in the MiSTer Github Repository. (SDRAM section is not filled in completely yet, you should assume the cores require SDRAM) + +| Core Name | SDRAM | +| ---------------------------------------------------------------------------------- | -------- | +| [Arkanoid](https://github.com/MiSTer-devel/Arcade-Arkanoid_MISTer) | | +| [AsteroidsDeluxe](https://github.com/MiSTer-devel/Arcade-AsteroidsDeluxe_MiSTer) | ✔️ | +| [Asteroids](https://github.com/MiSTer-devel/Arcade-Asteroids_MiSTer) | | +| [Astrocade](https://github.com/MiSTer-devel/Arcade-Astrocade_MiSTer) | ✔️ | +| [ATetris](https://github.com/MiSTer-devel/Arcade-ATetris_MiSTer) | | +| [Bagman](https://github.com/MiSTer-devel/Arcade-Bagman_MiSTer) | | +| [Berzerk](https://github.com/MiSTer-devel/Arcade-Berzerk_MiSTer) | | +| [BlackWidow](https://github.com/MiSTer-devel/Arcade-BlackWidow_MiSTer) | | +| [BombJack](https://github.com/MiSTer-devel/Arcade-BombJack_MiSTer) | | +| [Breakout](https://github.com/MiSTer-devel/Arcade-Breakout_MiSTer) | | +| [BurgerTime](https://github.com/MiSTer-devel/Arcade-BurgerTime_MiSTer) | | +| [BurningRubber](https://github.com/MiSTer-devel/Arcade-BurningRubber_MiSTer) | | +| [CanyonBomber](https://github.com/MiSTer-devel/Arcade-CanyonBomber_MiSTer) | | +| [Cave](https://github.com/MiSTer-devel/Arcade-Cave_MiSTer) | ✔️ | +| [Centipede](https://github.com/MiSTer-devel/Arcade-Centipede_MiSTer) | | +| [ComputerSpace](https://github.com/MiSTer-devel/Arcade-ComputerSpace_MiSTer) | | +| [Cosmic](https://github.com/MiSTer-devel/Arcade-Cosmic_MiSTer) | ✔️ | +| [CrazyBalloon](https://github.com/MiSTer-devel/Arcade-CrazyBalloon_MiSTer) | | +| [CrazyClimber](https://github.com/MiSTer-devel/Arcade-CrazyClimber_MiSTer) | | +| [CrazyKong](https://github.com/MiSTer-devel/Arcade-CrazyKong_MiSTer) | | +| [Defender](https://github.com/MiSTer-devel/Arcade-Defender_MiSTer) | | +| [DigDug](https://github.com/MiSTer-devel/Arcade-DigDug_MiSTer) | | +| [Dominos](https://github.com/MiSTer-devel/Arcade-Dominos_MiSTer) | | +| [DonkeyKong3](https://github.com/MiSTer-devel/Arcade-DonkeyKong3_MiSTer) | | +| [DonkeyKongJunior](https://github.com/MiSTer-devel/Arcade-DonkeyKongJunior_MiSTer) | | +| [DonkeyKong](https://github.com/MiSTer-devel/Arcade-DonkeyKong_MiSTer) | | +| [DottoriKun](https://github.com/MiSTer-devel/Arcade-DottoriKun_MiSTer) | | +| [Druaga](https://github.com/MiSTer-devel/Arcade-Druaga_MiSTer) | | +| [Finalizer](https://github.com/MiSTer-devel/Arcade-Finalizer_MiSTer) | | +| [FoodFight](https://github.com/MiSTer-devel/Arcade-FoodFight_MiSTer) | | +| [Frenzy](https://github.com/MiSTer-devel/Arcade-Frenzy_MiSTer) | | +| [Galaga](https://github.com/MiSTer-devel/Arcade-Galaga_MiSTer) | | +| [Galaxian](https://github.com/MiSTer-devel/Arcade-Galaxian_MiSTer) | | +| [Gaplus](https://github.com/MiSTer-devel/Arcade-Gaplus_MiSTer) | | +| [Gauntlet](https://github.com/MiSTer-devel/Arcade-Gauntlet_MiSTer) | | +| [Gyruss](https://github.com/MiSTer-devel/Arcade-Gyruss_MiSTer) | | +| [IremM62](https://github.com/MiSTer-devel/Arcade-IremM62_MiSTer) | | +| [IronHorse](https://github.com/MiSTer-devel/Arcade-IronHorse_MiSTer) | | +| [Jackal](https://github.com/MiSTer-devel/Arcade-Jackal_MiSTer) | ✔️ | +| [Jailbreak](https://github.com/MiSTer-devel/Arcade-Jailbreak_MiSTer) | | +| [Ladybug](https://github.com/MiSTer-devel/Arcade-LadyBug_MiSTer) | | +| [LunarLander](https://github.com/MiSTer-devel/Arcade-LunarLander_MiSTer) | | +| [MarioBros](https://github.com/MiSTer-devel/Arcade-MarioBros_MiSTer) | | +| [MCR1](https://github.com/MiSTer-devel/Arcade-MCR1_MiSTer) | | +| [MCR2](https://github.com/MiSTer-devel/Arcade-MCR2_MiSTer) | | +| [MCR3Mono](https://github.com/MiSTer-devel/Arcade-MCR3Mono_MiSTer) | | +| [MCR3Scroll](https://github.com/MiSTer-devel/Arcade-MCR3Scroll_MiSTer) | | +| [MCR3](https://github.com/MiSTer-devel/Arcade-MCR3_MiSTer) | | +| [MoonPatrol](https://github.com/MiSTer-devel/Arcade-MoonPatrol_MiSTer) | ✔️ | +| [MrDo](https://github.com/MiSTer-devel/Arcade-MrDo_MiSTer) | | +| [NinjaKun](https://github.com/MiSTer-devel/Arcade-NinjaKun_MiSTer) | | +| [Pacman](https://github.com/MiSTer-devel/Arcade-Pacman_MiSTer) | | +| [Pengo](https://github.com/MiSTer-devel/Arcade-Pengo_MiSTer) | | +| [Phoenix](https://github.com/MiSTer-devel/Arcade-Phoenix_MiSTer) | | +| [Pleiads](https://github.com/MiSTer-devel/Arcade-Pleiads_MiSTer) | | +| [PolyPlay](https://github.com/MiSTer-devel/Arcade-PolyPlay_MiSTer) | | +| [Pong](https://github.com/MiSTer-devel/Arcade-Pong_MiSTer) | | +| [Pooyan](https://github.com/MiSTer-devel/Arcade-Pooyan_MiSTer) | | +| [Popeye](https://github.com/MiSTer-devel/Arcade-Popeye_MiSTer) | | +| [QBert](https://github.com/MiSTer-devel/Arcade-QBert_MiSTer) | | +| [Rallyx](https://github.com/MiSTer-devel/Arcade-RallyX_MiSTer) | | +| [RiverPatrol](https://github.com/MiSTer-devel/Arcade-RiverPatrol_MiSTer) | | +| [Robotron](https://github.com/MiSTer-devel/Arcade-Robotron_MiSTer) | | +| [RushnAttack](https://github.com/MiSTer-devel/Arcade-RushnAttack_MiSTer) | | +| [ScooterShooter](https://github.com/MiSTer-devel/Arcade-ScooterShooter_MiSTer) | | +| [Scramble](https://github.com/MiSTer-devel/Arcade-Scramble_MiSTer) | ✔️ | +| [SEGASYS1](https://github.com/MiSTer-devel/Arcade-SEGASYS1_MiSTer) | | +| [SilverLand](https://github.com/MiSTer-devel/Arcade-SilverLand_MiSTer) | | +| [SkySkipper](https://github.com/MiSTer-devel/Arcade-SkySkipper_MiSTer) | | +| [SolomonsKey](https://github.com/MiSTer-devel/Arcade-SolomonsKey_MiSTer) | | +| [SpaceInvaders](https://github.com/MiSTer-devel/Arcade-SpaceInvaders_MiSTer) | ✔️ | +| [SpaceRace](https://github.com/MiSTer-devel/Arcade-SpaceRace_MiSTer) | | +| [Sprint1](https://github.com/MiSTer-devel/Arcade-Sprint1_MiSTer) | | +| [Sprint2](https://github.com/MiSTer-devel/Arcade-Sprint2_MiSTer) | | +| [Subs](https://github.com/MiSTer-devel/Arcade-Subs_MiSTer) | | +| [SuperBreakout](https://github.com/MiSTer-devel/Arcade-SuperBreakout_MiSTer) | | +| [Tecmo](https://github.com/MiSTer-devel/Arcade-Tecmo_MiSTer) | ✔️ | +| [TIAMC1](https://github.com/MiSTer-devel/Arcade-TIAMC1_MiSTer) | | +| [TimePilot84](https://github.com/MiSTer-devel/Arcade-TimePilot84_MISTer) | | +| [TimePilot](https://github.com/MiSTer-devel/Arcade-TimePilot_MiSTer) | | +| [TraverseUSA](https://github.com/MiSTer-devel/Arcade-TraverseUSA_MiSTer) | | +| [Ultratank](https://github.com/MiSTer-devel/Arcade-Ultratank_MiSTer) | | +| [VBall](https://github.com/MiSTer-devel/Arcade-VBall_MiSTer) | ✔️ | +| [Xevious](https://github.com/MiSTer-devel/Arcade-Xevious_MiSTer) | | +| [Zaxxon](https://github.com/MiSTer-devel/Arcade-Zaxxon_MiSTer) | ✔️ | +| [ZigZag](https://github.com/MiSTer-devel/Arcade-ZigZag_MiSTer) | | diff --git a/docs/cores/computer.md b/docs/cores/computer.md new file mode 100644 index 00000000..8644d01c --- /dev/null +++ b/docs/cores/computer.md @@ -0,0 +1,62 @@ +--- +hide: + - toc +--- + +Here is a list of the computer cores that are in the MiSTer Github Repository. + +| Core Name | System | /games/ Folder | SDRAM | +| -------------------------------------------------------------------- | ---------------------------------------------------------- | --------------- | -------- | +| [AcornAtom](https://github.com/MiSTer-devel/AcornAtom_MiSTer) | Acorn Atom | ./AcornAtom | | +| [AliceMC10](https://github.com/MiSTer-devel/AliceMC10_MiSTer) | Matra & Hachette Ordinateur Alice (TRS-80 MC-10 Clone) | ./AliceMC10 | | +| [Altair8800](https://github.com/MiSTer-devel/Altair8800_Mister) | MITS Altair 8800 | ./Altair8800 | | +| [AmstradPCW](https://github.com/MiSTer-devel/Amstrad-PCW_MiSTer) | Amstrad PCW | ./AmstradPCW | ✔️ | +| [Amstrad](https://github.com/MiSTer-devel/Amstrad_MiSTer) | Amstrad CPC 6128 | ./Amstrad | ✔️ | +| [ao486](https://github.com/MiSTer-devel/ao486_MiSTer) | 486DX33 (No FPU) compatible | ./AO486 | | +| [Apogee](https://github.com/MiSTer-devel/Apogee_MiSTer) | Apogee BK-01 / Radio-86RK | ./APOGEE | | +| [Apple-II](https://github.com/MiSTer-devel/Apple-II_MiSTer) | Apple IIe | ./Apple-II | | +| [Apple-I](https://github.com/MiSTer-devel/Apple-I_MiSTer) | Apple I | ./Apple-I | | +| [Aquarius](https://github.com/MiSTer-devel/Aquarius_MISTer) | Mattel Aquarius | ./AQUARIUS | | +| [Archie](https://github.com/MiSTer-devel/Archie_MiSTer) | Acorn Archimedes | ./ARCHIE | ✔️ | +| [Atari800](https://github.com/MiSTer-devel/Atari800_MiSTer) | Atari 800 / 800XL / 65XE / 130XE | ./Atari800 | Optional | +| [AtariST](https://github.com/MiSTer-devel/AtariST_MiSTer) | Atari ST / STe | ./AtariST | ✔️ | +| [BBCMicro](https://github.com/MiSTer-devel/BBCMicro_MiSTer) | BBC Micro B / Master 128K | ./BBCMicro | | +| [BK0011M](https://github.com/MiSTer-devel/BK0011M_MiSTer) | Elektronika BK (BK-0011M CPU) | ./BK0011M | ✔️ | +| [C16](https://github.com/MiSTer-devel/C16_MiSTer) | Commodore C16 / Plus/4 | ./C16 | | +| [C64](https://github.com/MiSTer-devel/C64_MiSTer) | Commodore 64 / Games System / 128 | ./C64 | ✔️ | +| [Chip8](https://github.com/MiSTer-devel/Chip8_MiSTer) | CHIP-8 by Joseph Weisbecker | ./Chip8 | | +| [CoCo2](https://github.com/MiSTer-devel/CoCo2_MiSTer) | Tandy Color Computer 2 / Dragon 32 | ./CoCo2 | | +| [CoCo3](https://github.com/MiSTer-devel/CoCo3_MiSTer) | Tandy Color Computer 3 | ./CoCo3 | | +| [EDSAC](https://github.com/MiSTer-devel/EDSAC_MiSTer) | EDSAC | ./EDSAC | | +| [Galaksija](https://github.com/MiSTer-devel/Galaksija_MiSTer) | Galaksija by Voja Antonić | ./Galaksija | | +| [Interac](https://github.com/MiSTer-devel/Interact_MiSTer) | Interact Home Computer | ./Interac | | +| [Jupiter](https://github.com/MiSTer-devel/Jupiter_MiSTer) | Jupiter Ace | ./Jupiter | | +| [Laser310](https://github.com/MiSTer-devel/Laser310_MiSTer) | Vtech Laser 310 | ./Laser | | +| [MacPlus](https://github.com/MiSTer-devel/MacPlus_MiSTer) | Macintosh Plus | ./MacPlus | ✔️ | +| [Minimig-AGA](https://github.com/MiSTer-devel/Minimig-AGA_MiSTer) | Commodore Amiga 500 / 600 / 1200 / 4000 / CD32 | ./Amiga | ✔️ | +| [MSX](https://github.com/MiSTer-devel/MSX_MiSTer) | Microsoft MSX / MSX2 / Plus / MSX3 / TurboR | ./MSX | ✔️ | +| [MultiComp](https://github.com/MiSTer-devel/MultiComp_MiSTer) | Grant Searle's MultiComp | ./MultiComp | | +| [OndraSPO186](https://github.com/MiSTer-devel/OndraSPO186_MiSTer) | Tesla Ondra SPO-186 | ./Ondra_SPO186 | | +| [Orao](https://github.com/MiSTer-devel/Orao_MiSTer) | PEL Varaždin Orao / Eagle | ./ORAO | | +| [Oric](https://github.com/MiSTer-devel/Oric_MiSTer) | Tangerine Oric / Oric-1 | ./Oric | | +| [PC88](https://github.com/MiSTer-devel/PC88_MiSTer) | NEC PC8801 MKII SR | ./PC8801 | | +| [PDP1](https://github.com/MiSTer-devel/PDP1_MiSTer) | DEC PDP-1 | ./PDP1 | | +| [PET2001](https://github.com/MiSTer-devel/PET2001_MiSTer) | Commodore PET 2001 | ./PET2001 | | +| [PMD85](https://github.com/MiSTer-devel/PMD85_MiSTer) | Tesla PMD 85 | ./PMD85 | | +| [QL](https://github.com/MiSTer-devel/QL_MiSTer) | Sinclair QL | ./QL | ✔️ | +| [RX-78](https://github.com/MiSTer-devel/RX-78_MiSTer) | Bandai RX-78 | ./RX78 | | +| [SAM-Coupe](https://github.com/MiSTer-devel/SAM-Coupe_MiSTer) | Miles Gordon Technology SAM Coupé | ./SAMCOUPE | ✔️ | +| [SharpMZ](https://github.com/MiSTer-devel/SharpMZ_MiSTer) | Sharp MZ | ./SharpMZ | | +| [SordM5](https://github.com/MiSTer-devel/SordM5_MiSTer) | Sord M5 | ./Sord M5 | | +| [Specialist](https://github.com/MiSTer-devel/Specialist_MiSTer) | Specialist / Специалист | | | +| [SVI328](https://github.com/MiSTer-devel/SVI328_MiSTer) | Spectravideo SV-328 | ./SVI328 | | +| [TI-99_4A](https://github.com/MiSTer-devel/TI-99_4A_MiSTer) | Texas Instruments TI-99/4A | ./TI-99_4A | | +| [TRS-80](https://github.com/MiSTer-devel/TRS-80_MiSTer) | Radio Shack / Tandy TRS-80 Micro Computer System / Model I | ./TRS-80 | | +| [TSConf](https://github.com/MiSTer-devel/TSConf_MiSTer) | TSConf (ZX-Evolution Improvement) | ./TSConf | ✔️ | +| [UK101](https://github.com/MiSTer-devel/UK101_MiSTer) | Compukit UK101 | ./UK101 | | +| [Vector-06C](https://github.com/MiSTer-devel/Vector-06C_MiSTer) | Vector-06C / Вектор-06Ц | ./VECTOR06 | | +| [VIC20](https://github.com/MiSTer-devel/VIC20_MiSTer) | Commodore VIC-20 | ./VIC20 | | +| [X68000](https://github.com/MiSTer-devel/X68000_MiSTer) | Sharp X68000 | ./X68000 | ✔️ | +| [ZX-Spectrum](https://github.com/MiSTer-devel/ZX-Spectrum_MISTer) | Sinclair ZX Spectrum | ./Spectrum | ✔️ | +| [ZX81](https://github.com/MiSTer-devel/ZX81_MiSTer) | Sinclair ZX80 / ZX81 | ./ZX81 | | +| [ZXNext](https://github.com/MiSTer-devel/ZXNext_MISTer) | ZX Spectrum Next | ./ZXNext | | diff --git a/docs/cores/console.md b/docs/cores/console.md new file mode 100644 index 00000000..298e6dab --- /dev/null +++ b/docs/cores/console.md @@ -0,0 +1,34 @@ +--- +hide: + - toc +--- + +Here is a list of the console cores that are in the MiSTer Github Repository. + +| Core Name | Systems | /games/ Folder | BIOS | SDRAM | +| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| [AY-3-8500](https://github.com/MiSTer-devel/AY-3-8500-MiSTer) | "Pong-on-a-chip" | ./AY-3-8500 | | | +| [Arcadia](https://github.com/MiSTer-devel/Arcadia_MiSTer) | Emerson Arcadia 2001 | ./Arcadia | | | +| [Astrocade](https://github.com/MiSTer-devel/Astrocade_MiSTer) | Bally Astrocade | ./Astrocade | boot.rom = Astrocade BIOS | | +| [Atari2600](https://github.com/MiSTer-devel/Atari2600_MiSTer) | Atari 2600
Atari VCS | ./Atari2600 | | | +| [Atari5200](https://github.com/MiSTer-devel/Atari800_MiSTer) | Atari 5200 SuperSystem | ./Atari5200 | | | +| [Atari7800](https://github.com/MiSTer-devel/Atari7800_MiSTer) | Atari 7800 ProSystem
Atari 2600 Support | ./Atari7800 | boot0.rom = BIOS (optional) | ✔️ | +| [AtariLynx](https://github.com/MiSTer-devel/AtariLynx_MiSTer) | Atari Lynx | ./AtariLynx | boot.rom = bootrom (lynxboot.img) | | +| [ChannelF](https://github.com/MiSTer-devel/ChannelF_MiSTer) | Fairchild Channel F | ./ChannelF | | | +| [ColecoVision](https://github.com/MiSTer-devel/ColecoVision_MiSTer) | ColecoVision
Sega SG-1000 | ./Coleco
./SG1000 | | ✔️ | +| [GBA](https://github.com/MiSTer-devel/GBA_MiSTer) | Nintendo Game Boy Advance | ./GBA | boot.rom = BIOS (recommended) | Optional | +| [GBA2P](https://github.com/MiSTer-devel/GBA_MiSTer/tree/GBA2P) | 2x Game Boy Advance (2-Player) | ./GBA2P | boot.rom = BIOS (recommended) | ✔️ | +| [GameBoy](https://github.com/MiSTer-devel/Gameboy_MiSTer) | Nintendo Game Boy | ./Gameboy | boot1.rom = Gameboy Color BIOS
boot2.rom = autoload a game | ✔️ | +| [Gameboy2P](https://github.com/MiSTer-devel/Gameboy_MiSTer/tree/Gameboy2P) | 2x Game Boy (2-Player) | ./Gameboy2P | boot1.rom = Gameboy Color BIOS
boot2.rom = autoload a game | ✔️ | +| [Genesis](https://github.com/MiSTer-devel/Genesis_MiSTer) | Sega Genesis
Sega Mega Drive | ./Genesis | | Optional | +| [Intv](https://github.com/MiSTer-devel/Intv_MiSTer) | Mattel Intellivision | ./Intv | boot0.rom = exec.bin
boot1.rom = grom.bin
boot2.rom = sp0256-012.bin
boot3.rom = ecs.bin | | +| [MegaCD](https://github.com/MiSTer-devel/MegaCD_MiSTer) | Sega CD
Sega Mega-CD | ./MegaCD | boot.rom = BIOS
cd\_bios.rom = separate folder BIOS | ✔️ | +| [NES](https://github.com/MiSTer-devel/NES_MiSTer) | Nintendo Entertainment System
Famicom Disk System
NSF Music Player | ./NES | boot0.rom = FDS BIOS
boot1.rom = NES Cart (optional)
boot2.rom = blank FDS image (optional)
boot3.rom = .PAL Palette File (optional) | ✔️ | +| [NeoGeo](https://github.com/MiSTer-devel/NeoGeo_MiSTer) | SNK Neo Geo AES & MVS | ./NeoGeo | 000-lo.lo
sfix.sfix
sp-s2.sp1 (MVS)
neo-epo.sp1 (AES)
uni-bios.rom | ✔️ | +| [Odyssey2](https://github.com/MiSTer-devel/Odyssey2_MiSTer) | Magnavox Odyssey 2
Philips Odyssey 2
Philips Videopac G7000 | ./Odyssey2 | | | +| [SMS](https://github.com/MiSTer-devel/SMS_MiSTer) | Sega Master System
Sega Game Gear
Sega SG-1000 | ./SMS
./SG1000 | | ✔️ | +| [SNES](https://github.com/MiSTer-devel/SNES_MiSTer) | Super Nintendo Entertainment System
Nintendo Satellaview
SPC Music Player | ./SNES | bsx\_bios.rom = Satellaview ROM | ✔️ | +| [TurboGrafx16](https://github.com/MiSTer-devel/TurboGrafx16_MiSTer) | NEC TurboGrafx-16 / PC Engine
CD-ROM² / Super CD-ROM²
Duo / TurboDuo
SuperGrafx
Arcade Card | ./TGFX16
./TGFX16-CD | cd\_bios.rom = BIOS Place in tgfx16-cd | Optional | +| [VC4000](https://github.com/MiSTer-devel/VC4000_MiSTer) | Interton VC4000
Acetronic MPU-1000
Occitane OC2000 | ./VC4000 | | | +| [Vectrex](https://github.com/MiSTer-devel/Vectrex_MiSTer) | Vectrex | ./Vectrex | | | +| [WonderSwan](https://github.com/MiSTer-devel/WonderSwan_MiSTer) | Bandai WonderSwan
WonderSwan Color
SwanCrystal | ./WonderSwan | boot.rom = WonderSwan bootrom
boot1.rom = WonderSwan Color bootrom | ✔️ | diff --git a/docs/cores/features/cheats.md b/docs/cores/features/cheats.md new file mode 100644 index 00000000..dc899114 --- /dev/null +++ b/docs/cores/features/cheats.md @@ -0,0 +1,38 @@ +Some of MiSTer's cores have the capability to apply cheats in-game. The cheats are in a specific format and are automatically pulled from [gamehacking.org's](https://gamehacking.org/){target=_blank} website when you run the downloader script. These cheat files have specific rules that govern how they can be used. + +## Setup +Cheats should be stored in: `cheats/system/rom_filename.zip` where system is name of the core like NES, SNES, Genesis, etc... + +So, for example: + +`cheats/NES/Taboo (USA).zip` for the NES ROM `Taboo (USA).nes` + +The filename of the zip must match the ROM name exactly. Cheats will be loaded automatically when you load a ROM, and can be enabled and disabled from the menu in supported cores. + +If the .zip cheat file does not match the ROM name, the cheat engine will automatically check the ROM CRC32 and select the appropriate .zip cheat file with matching CRC32 accordingly. ROM name matching has priority over CRC32 checking. + +Individual cheats are in .gg format and should be stored in zip files. + +## How to use Cheats with CD-ROM images +Since CD-ROM images are large, the MiSTer purposefully doesn't do CRC32 hash checks for CD images. You will need to place the cheats you want into the same folder as your cue/bin or CHD file, in order to use cheats with it. Typically the cheat-matching with your CD-ROM image is done by matching the filename of your CUE/BIN, CHD, or ISO with the filename of the cheat zip file. The Playstation core uniquely allows for this method and has an additional method to load the cheat based upon the internal Game ID (e.g. SCUS-94163). Please note, if the cheats do not load, then check the following: + +1. The cheat zip file is in the same subfolder as the desired CUE/BIN, CHD, or ISO. +2. The filename of the zip file is identical to the filename of the CUE/BIN, CHD, or ISO. +3. **(for the PSX core only)** The Game ID of the desired game matches the target Game ID of the zip file. + +If cheats for the CD game do not work when everything else looks correct, it is possible your version of the game is wrong. + +## Making your own codes +All types of cheat codes for 16 bit systems and earlier can be decoded into four pieces of information: An address, a compare value, a replace value, and usually a flag to say if the compare value is used or not. The format for a gg file is in binary as 4 32 bit integers in little-endian byte order. + +For example, if the Address is `0xFF1CA0` and the compare value is `0xB5` and the replace value is `0xFF`, the file would look like this: + +`01 00 00 00 A0 1C FF 00 B5 00 00 00 FF 00 00 00` + +The first four bytes are little-endian `0x00000001` for "compare enabled", the second four are little-endian address, third set are compare value, and fourth is replace value. Note that not all codes use a compare value. + +For cheats with multiple codes, simply add another 16 bytes at the end of the file in the same format as the first. + +You can decode game genie codes into these values with tools like this: + +[https://gamehacking.org/system/nes](https://gamehacking.org/system/nes){target=_blank} diff --git a/docs/cores/highlights/atari7800.md b/docs/cores/highlights/atari7800.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/cores/highlights/files/boot2.rom b/docs/cores/highlights/files/boot2.rom new file mode 100644 index 00000000..5fcc1328 Binary files /dev/null and b/docs/cores/highlights/files/boot2.rom differ diff --git a/docs/cores/highlights/gb2p.md b/docs/cores/highlights/gb2p.md new file mode 100644 index 00000000..55c961b0 --- /dev/null +++ b/docs/cores/highlights/gb2p.md @@ -0,0 +1,2 @@ +## Game Boy 2-Player Demonstration +![type:video](videos/gb2p.mp4) diff --git a/docs/cores/highlights/genesis.md b/docs/cores/highlights/genesis.md new file mode 100644 index 00000000..053227b7 --- /dev/null +++ b/docs/cores/highlights/genesis.md @@ -0,0 +1,33 @@ +The Genesis core is a port of the [fpgagen](https://github.com/Torlus/fpgagen){target=_blank} core to MiSTer, with significant enhancements and additions. + +## Features +* Composite Blending effect (e.g. Sonic Waterfall transparency) +* CPU Turbo option (e.g. Road Rash gameplay speed) +* Increase sprite limit. +* Audio Filtering options for Model 1, Model 2, Minimal, and No Filter +* Switch between YM2612 (Model 1) or YM3438 (Model 2/3) FM Synth +* Multitap: 4-way, Team Player, J-Cart +* SVP Chip (Virtua Racing for Genesis supported) +* Auto-Region header detection using the [new style and the old style combined](https://plutiedev.com/rom-header#region){target=_blank}. +* Corrected Aspect Ratio option for 320x224 game resolutions (e.g. Castlevania Moon). + +## Region detection +There are two methods of region detection. + +1. Header: This method detects a character in the header to determine if the game was intended to be played on a Japanese, European, or American version of the console. This method is default and preferred as it is compatible with the entire commercial lineup. This option uses a region priority setting for multi-region games which had "JUE" in the header. Whatever the first region is, will be the region set on load of a multi-region game. + +2. File Ext: This method changes the region according to the filename extension of the rom. + * BIN = Japanese + * GEN = America + * MD = Europe + +There is also a region priority list for multi-region games that had multiple region codes in the header. This is useful if you want to specify a certain region to default to in order of first priority to last (e.g. US>JP>EU will try to load multi-region games in US first, then it will load as JP if no US region code is present, then EU if neither is present). + +## Corrected Aspect Ratio Example Video +![type:video](videos/genesis-car.mp4) + +## Composite Effect Example Video +![type:video](videos/genesis-comp.mp4) + +## Turbo CPU Example Video +![type:video](videos/genesis-turbo.mp4) diff --git a/docs/cores/highlights/nes.md b/docs/cores/highlights/nes.md new file mode 100644 index 00000000..f619b6d7 --- /dev/null +++ b/docs/cores/highlights/nes.md @@ -0,0 +1,19 @@ +The Nintendo Entertainment System (NES) MiSTer core is packed full of many features to be explored. There are options like automatic Famicom Disk System (FDS) disk swapping, custom palette loading, overscan and screen edge masking, extra sprites hack, and SNAC (so you could use an original Zapper lightgun on a CRT with analog video output). + +## Extra Sprites mode +Some NES games would allow more sprites on the screen than the system was typically designed to allow at one time and the sprites would flicker to keep them on the screen. There was a limit to how many sprites could be on the screen at one time. The NES MiSTer core lets you somewhat remove this limit, reducing the amount of flicker that occurs when many sprites are on the screen in games like Rygar. This does not work with all games that have flicker, some flicker was added intentionally by the original developers for other reasons. + +### Extra Sprites (deflicker) Example Video +![type:video](videos/nes-flicker.mp4) + +## Palettes +The NES core has both built-in palettes and the ability to load custom palettes. You may be wondering why the NES core needs palettes. It's just colors, right? Without going into it here, if you want to learn about NES Palettes, watch [this YouTube video by NesHacker](https://www.youtube.com/watch?v=7Co_8dC2zb8), and read the pinned comment there as a couple details were technically inaccurate. Basically, the NES does not have a native palette of colors to work with as the colors were not output in the typical red, green, and blue values like other game consoles. So emulators need to come up with palettes that most closely approximate the original viewing experience. This viewing experience would sometimes vary depending on the tv you were watching on, so multiple palette options are made available. This also makes it possible to do fun and ridiculous palettes just for the sake of it, like the virtual boy palette made by RetroSho. + +### Palettes Example Video +![type:video](videos/palettes.mp4) + +## Famicom Disk System BIOS boot. +[Download Blank FDS boot2.rom](files/boot2.rom){target=_blank} and then place this in `./games/NES/`. Then when you start the core (assuming you already have the FDS bios placed there and renamed to `boot0.rom`) it will boot to the FDS BIOS as if you had a blank disk inserted. + +### Famicom Disk System Blank Disk Boot Example Video +![type:video](videos/fdsbios.mp4) \ No newline at end of file diff --git a/docs/cores/highlights/snes.md b/docs/cores/highlights/snes.md new file mode 100644 index 00000000..40a5b65c --- /dev/null +++ b/docs/cores/highlights/snes.md @@ -0,0 +1,34 @@ +The Super Nintendo Entertainment System (or SNES) MiSTer core has multiple features like CPU and Super FX chip turbo mode, lightgun support, mouse support, and even changing the WRAM initialization value. In addition to this, it also has support for nearly every single enhancement chip released. It is a very powerful core that was primarily developed by [srg320](https://www.patreon.com/srg320){target=_blank} when he didn't even have original hardware. + +## Enhancement Chip Support +Here are the SNES enhancement chips currently supported with some example games they were used in: + +* Super FX AKA GSU-1 (Star Fox, Star Fox 2, Stunt Race FX) +* Super FX 2 AKA GSU-2 (Super Mario World 2: Yoshi's Island, Doom) +* CX4 (Only in Mega Man X 2 and Mega Man X 3) +* DSP-1 (Super Mario Kart and Pilotwings) +* DSP-2 (Only in Dungeon Master) +* DSP-3 (Only in SD Gundam GX) +* DSP-4 (Only in Top Gear 3000) +* OBC-1 (Only used in Metal Combat: Falcon's Revenge) +* S-DD1 (Only used in Star Ocean and Street Fighter Alpha 2) +* SA-1 (Kirby Series, Super Mario RPG) +* SPC7110 (Far East of Eden Zero, Large Shell beast Story 2) +* ST1010 (F1 Roc 2 - Race of Champions) +* S-RTC (Daikaiju Monogatari II) + +Currently the only enhancement chips not supported are GB-Z80 (Super Game Boy), MX15001TFC (Nintendo Power Flash Cartridges), ST011 (Hayazashi Nidan Morita Shougi), and ST018 (Hayazashi Nidan Morita Shougi 2). This is mostly because the core is already near the limit of what the DE10-Nano's Cyclone V is capable of fitting into it's design. + +### SNES Enancement Chip Example Video +![type:video](videos/snes-chips.mp4) + +## Satellaview Support +This core also supports Satellaview. You just need the BSX/BS-X rom placed into the `./games/SNES/` folder and renamed to `bsx_bios.rom`. The core used to require patched versions of the rom to run, but every original Satellaview ROM that didn't require an internet connection, extra peripherals, or something like that will run now without patches. + +### BS-X Satellaview Example Video +![type:video](videos/snes-bs-x.mp4) + +## Super FX Turbo +The MiSTer SNES core has a Super FX Turbo option which overclocks the Super FX chip so games run a little faster. Combined with the Turbo CPU option games like Star Fox will have a higher framerate. However, the game will run faster than intended so your results may vary. It is also important to note that the use of such hacks may increase the likelihood of bugs occurring, so please do not report bugs when using Turbo options. +### Super FX Turbo Example Video +![type:video](videos/snes-fx-turbo.mp4) diff --git a/docs/cores/highlights/tgfx16.md b/docs/cores/highlights/tgfx16.md new file mode 100644 index 00000000..b25eff77 --- /dev/null +++ b/docs/cores/highlights/tgfx16.md @@ -0,0 +1 @@ +show off system, use github readme as reference, focus on features diff --git a/docs/cores/highlights/videos/fdsbios.mp4 b/docs/cores/highlights/videos/fdsbios.mp4 new file mode 100644 index 00000000..61947389 Binary files /dev/null and b/docs/cores/highlights/videos/fdsbios.mp4 differ diff --git a/docs/cores/highlights/videos/gb2p.mp4 b/docs/cores/highlights/videos/gb2p.mp4 new file mode 100644 index 00000000..169b12f7 Binary files /dev/null and b/docs/cores/highlights/videos/gb2p.mp4 differ diff --git a/docs/cores/highlights/videos/genesis-car.mp4 b/docs/cores/highlights/videos/genesis-car.mp4 new file mode 100644 index 00000000..73bfe321 Binary files /dev/null and b/docs/cores/highlights/videos/genesis-car.mp4 differ diff --git a/docs/cores/highlights/videos/genesis-comp.mp4 b/docs/cores/highlights/videos/genesis-comp.mp4 new file mode 100644 index 00000000..d43fafcc Binary files /dev/null and b/docs/cores/highlights/videos/genesis-comp.mp4 differ diff --git a/docs/cores/highlights/videos/genesis-turbo.mp4 b/docs/cores/highlights/videos/genesis-turbo.mp4 new file mode 100644 index 00000000..5e10b818 Binary files /dev/null and b/docs/cores/highlights/videos/genesis-turbo.mp4 differ diff --git a/docs/cores/highlights/videos/nes-flicker.mp4 b/docs/cores/highlights/videos/nes-flicker.mp4 new file mode 100644 index 00000000..290ea0c7 Binary files /dev/null and b/docs/cores/highlights/videos/nes-flicker.mp4 differ diff --git a/docs/cores/highlights/videos/palettes.mp4 b/docs/cores/highlights/videos/palettes.mp4 new file mode 100644 index 00000000..c125934b Binary files /dev/null and b/docs/cores/highlights/videos/palettes.mp4 differ diff --git a/docs/cores/highlights/videos/snes-bs-x.mp4 b/docs/cores/highlights/videos/snes-bs-x.mp4 new file mode 100644 index 00000000..6fbea726 Binary files /dev/null and b/docs/cores/highlights/videos/snes-bs-x.mp4 differ diff --git a/docs/cores/highlights/videos/snes-chips.mp4 b/docs/cores/highlights/videos/snes-chips.mp4 new file mode 100644 index 00000000..0b7e8dee Binary files /dev/null and b/docs/cores/highlights/videos/snes-chips.mp4 differ diff --git a/docs/cores/highlights/videos/snes-fx-turbo.mp4 b/docs/cores/highlights/videos/snes-fx-turbo.mp4 new file mode 100644 index 00000000..70ca325a Binary files /dev/null and b/docs/cores/highlights/videos/snes-fx-turbo.mp4 differ diff --git a/docs/cores/img/cyclone-iv-decap.png b/docs/cores/img/cyclone-iv-decap.png new file mode 100644 index 00000000..bb88524c Binary files /dev/null and b/docs/cores/img/cyclone-iv-decap.png differ diff --git a/docs/cores/paths.md b/docs/cores/paths.md new file mode 100644 index 00000000..fb0c0e6d --- /dev/null +++ b/docs/cores/paths.md @@ -0,0 +1,29 @@ +--- +hide: + - toc +--- + +The standard paths are of the form `/media/fat/games/`, where `` is the core name of the given system. + +Please check the respective README file for each core to determine the appropriate full path. + +## Standard USB Core Paths +They are of the form `/media/usb<0..5>/games/`. Where `<0..5>` indicates the number of USB drives mounted by the operating system. + +## Standard CIFS Core Paths +They are of the form `/media/fat/cifs/games/`. + +## Other Paths +There are other valid paths, that are available for backwards-compatibility reasons, and also to ease testing. You should use the standard paths instead whenever possible. + +## Path Priority +There is a priority order of core paths. When you plug in a USB drive and it has a folder `/games/PSX` on it (mounted locally as `/media/usb<0..5>/games/PSX` when plugged in), then the MiSTer PSX core will look to that folder on the USB drive instead of the local one on the MicroSD at `/media/fat/games/PSX`. Here is the priority list from [Main_MiSTer's file_io.cpp](https://github.com/MiSTer-devel/Main_MiSTer/blob/master/file_io.cpp#L922){target=_blank} in order of highest priority to lowest: + +1. `/media/fat` +2. `/media/usb<0..5>` +3. `/media/usb<0..5>/games` +4. `/media/fat/cifs` +5. `/media/fat/cifs/games` +6. `/media/fat/games` + +If the core's folder isn't found in any of these it should create the folder. diff --git a/docs/cores/what.md b/docs/cores/what.md new file mode 100644 index 00000000..1f81f2ad --- /dev/null +++ b/docs/cores/what.md @@ -0,0 +1,16 @@ +--- +hide: + - toc +--- + +In MiSTer terminology, a "core" is the current system that the FPGA is configured to simulate. It is configured as the "Menu" core when you power on the MiSTer for the first time. Then, if you use the OSD and go to `_Console` and then select `NES`, it will configure the FPGA to be the "NES" core. + +The term "core" has been used by Hardware Description Language (HDL) developers in a way which refers to the things that are programmed onto the FPGA. So for instance, the MiSTer FPGA framework uses Intel's "Altera PLL Core". This is a chunk of logic that is portable which allows developers to hook up to the clock on the chip. There are HDMI cores, ethernet cores, serial data cores, and so on... + +However, for MiSTer, a core refers to the system being emulated. So you have the [PSX (Playstation) core](https://github.com/MiSTer-devel/PSX_MiSTer){target=_blank}, the [Minimig (Amiga) core](https://github.com/MiSTer-devel/Minimig-AGA_MiSTer){target=_blank}, the [SNES core](https://github.com/MiSTer-devel/SNES_MiSTer){target=_blank}, and so many more to explore. + +## What happens when I load a core? + +Imagine every time you load a core you are connecting a different console, computer, or arcade system to your television. You select the Genesis core in the menu and load it, you have now essentially plugged a Genesis into your television without all the hassle of wrestling with cables. That's the concept. What actually is happening is that `.rbf` file is reprogramming the FPGA chip to take on a different form. It used to contain the digital logic required to be an NES combined with the MiSTer FPGA core components, and it turned into a chip with the digital logic for the Genesis combined with the the MiSTer FPGA core components. + +Now, you may be worried that all of this rewriting of the FPGA could reduce it's lifespan. This isn't something to worry about, these kinds of FPGA's (SRAM-based) are considered to have an indefinite number of writes. Many millions of rewrites to the same sector are normal and nothing to worry about. diff --git a/docs/developer/conf_str.md b/docs/developer/conf_str.md new file mode 100644 index 00000000..19d50b5b --- /dev/null +++ b/docs/developer/conf_str.md @@ -0,0 +1,116 @@ +--- +hide: + - toc +--- + +MiSTer provides an on-screen display (OSD) that can be toggled on and off by pressing F12 on your keyboard (or OSD button). For each core that is loaded, this menu can be configured to add specific options for that core. + +The top-level module for the cores is `emu`. This does **NOT** mean `emu` is the top-level module for the project, but rather it is the top-level module for our purposes. The `emu` module is typically found in the SystemVerilog file (`*.sv` extension) with the same name as the project. As an example, the Arcade-Galaga project has it's top-level module at `Arcade-Galaga.sv`. + +The configuration string is stored in the variable `CONF_STR` of the `emu` module. This variable is passed to the `hps_io` module that handles sending it to the processor to be read when necessary. + +Each line of the configuration string is delimited with a semicolon. + +Most cores have a Status Bit Map placed at the top of the `CONF_STR` section. When developing a core, please use this as it's a helpful reference which aids in collaboration. This reference is edited by fellow developers to communicate which status bits are occupied. Only one option can occupy `status[8]` so this is important. + +## Status Bit Map + +For example with nothing occupied: + +``` +// Status Bit Map: +// Upper Lower +// 0 1 2 3 4 5 6 +// 01234567890123456789012345678901 23456789012345678901234567890123 +// 0123456789ABCDEFGHIJKLMNOPQRSTUV 0123456789ABCDEFGHIJKLMNOPQRSTUV +// +``` + +If you add a status bit option like `O89` to the core configuration string, this is going to use the first group of status bits on the left since the "O" for option is capitalized (marked Upper). Then it's going to use 8 and 9, this is from the bottom row (which is alphanumeric). So you would update the index after using these like so: + +``` +// Status Bit Map: +// Upper Lower +// 0 1 2 3 4 5 6 +// 01234567890123456789012345678901 23456789012345678901234567890123 +// 0123456789ABCDEFGHIJKLMNOPQRSTUV 0123456789ABCDEFGHIJKLMNOPQRSTUV +// XX +``` + +This will communicate to other developers that `status[9:8]` are occupied and should not be used. + +## Valid options for the menu + +`[]` - means optional parameter + +* `C[,{Text}]` - Enables a cheat menu entry with the label `{Text}`. +* `CHEAT` - like DIP, for arcades with a cheat system +* `D{Index}` - Prefix which disables the option if `menumask[Index]` is set. +* `d{Index}` - Same as 'D', but disables the option if `menumask[Index]` is NOT set. +* `DIP` - in arcade cores, this will display the DIP menu from the MRA +* `F[S][#],{Ext}[,{Text}][,{Address}]` - Load file button. + * `{Ext}` - a concatenated list of 3 character file extensions. For example, `BINGEN` would be `BIN` and `GEN` extensions. + * Optional `{Text}` string is the text that is displayed before the extensions like "Load RAM". If `{Text}` is not specified, then default is "Load \*". + * Optional `[S]` - core supports save files, load a file, and mount a save for reading or writing + * `#` is explicit index (or index is generated from line number if index not given). + * Optional `{Address}` - load file directly into DDRAM at this address + * ioctl_index from hps_io will be: ioctl_index[5:0] = index(explicit or auto), ioctl_index[7:6] = extension index +* `FC[#],{Ext}[,{Text}][,{Address}]` - Open file and remember it, useful for remembering an alternative rom, config, or other type of file. See F for how the options work. + +* `H{Index}` - Prefix which hides the option if `menumask[Index]` is set. +* `h{Index}` - Same as `H`, but hides the option if `menumask[Index]` is NOT set. +* `O{Index1}[{Index2}],{Name},{Options...}` - Option button that allows you to select between various choices. + * `{Index1}` and `{Index2}` are values from 0-9 and A-V (like Hex but it extends from A-V instead of A-F). This represents all 31 bits. First and second index are the range of bits that will be set in the status register. + * `{Name}` is what is shown to describe the option. + * `{Options...}` - a list of comma separated options. +* `P{#},{Title}` - Creates sub-page for options with `{Title}`. +* `P{#}` - Prefix to place the option into specific `{#}` page. This is added before `O#` but after something like `d#`. (e.g. `"d5P1o2,Vertical Crop,Disabled,216p(5x);",` is correct and `"P1d5o2,Vertical Crop,Disabled,216p(5x);",` is incorrect and the menu options will not work.) +* `R{Index},{Name}` - Same as T option but closes the OSD after selecting. Convenient for Reset option. +* `S{Slot},{Ext}[,{Text}]` - Mount SD card button. + * `{Slot}` - a value from 0-3. Up to four images can be mounted at the same time. + * `{Ext}` - same as in `F` option. + * (Optional) `{Text}` - The text that is displayed before the extensions like "Load RAM". If `{Text}` is not specified, then default is "Mount \*". +* `T{Index},{Name}` - Trigger button. This is a simple button that will pulse HIGH of specified `{Index}` bit in status register. A perfect example of this is for a reset button. + * `{Name}` is the text that describes the button function. +* `-[,TEXT]` - empty (or with `TEXT`) line. +* Lower case options `o`,`t`,`r` equal their upper case variants with adding 32 to status bit indexes. + +## Non-OSD options + +These must be placed at the bottom of the configuration string: + +* `J[1],{Button1}[,{Button2},...]` - J1 means lock keyboard to joystick emulation mode. Useful for keyboard-less systems such as consoles. {Button1},{Button2},... is list of joystick buttons used in the core. Up to 12 buttons can be listed. Analog axis are not defined here. The user just needs to map them through the Menu core. +* `jn,{SNES Button Name1},[,{SNES Button2},...]` - this sets the default mapping of the buttons. ie: jn,A would map joystick bit 4 to the A button on a SNES style controller automatically +* `jp` - same as `jn` but used when `gamepad_defaults=1` in `MiSTer.INI`. Typically refers to positional mapping relative to a SNES controller +* `V,{Version String}` - Version string. {Version String} is the version string. Takes the core name and appends version string for name to display. +* `I,INFO1,INFO2,...,INFO255` - `INFO1-INFO255` lines to display as OSD info (top left corner of screen). +* `DEFMRA,{mra name}` - default MRA (ie: Puckman.mra) to be used when core is uploaded by USB blaster (debug) + +## jn vs. jp and mapping conventions + +* jn mapping is the default. +* jp mapping is used when the INI file has gamepad_defaults=1 +* the only difference in the two mappings is the "philosophy" of how they are expected to work + +The difference is one of convention when mapping buttons: +* jn is name-base mapping +* jp is position-based mapping + +**What does this mean?** + +Consider how the internal gamepad is defined on MiSTer: + +1. Internally, controllers are mapped in the menu core to a SNES-style gamepad +2. The button order on the internal MiSTer gamepad is ABXYLR + Start + Select +3. That is: button 1=A, button 2=B, and so on. + +With "jn" mapping: +* the convention is to map button A of the core to the internal "SNES A" button. +* If the core has no button "A", this would be the first button. +* Second button would be "SNES B", and so forth. +* This is because the name or order of the button matches the original definition (ABYXLR etc) + +With "jp" mapping: +* the convention is to consider the physical location of each button +* For a Genesis 3-button controller that has A, B, C as buttons, mapping would be "SNES Y, SNES B, SNES A" +* This is because YBA on a SNES gamepad are the lower 3 buttons of the controller diff --git a/docs/developer/links.md b/docs/developer/links.md new file mode 100644 index 00000000..7f8202ed --- /dev/null +++ b/docs/developer/links.md @@ -0,0 +1,33 @@ +--- +hide: + - toc +--- + +Here's some useful links for experienced and new developers: + +## FPGA Tutorials +[Alanswx's MiSTer Tutorials series](https://github.com/alanswx/Tutorials_MiSTer){target=_blank} +[FPGA4Fun](https://www.fpga4fun.com/){target=_blank} +[My First FPGA](https://www.terasic.com.tw/cgi-bin/page/archive_download.pl?Language=English&No=1046&FID=86a1c2f74b7ff8a8abf58d2b4689d4be){target=_blank} + +## MiSTer Development Resources +[MiSTer FPGA Core Template](https://github.com/MiSTer-devel/Template_MiSTer){target=_blank} +[JimmyStones' Verilator Template](https://github.com/JimmyStones/Verilator_Template){target=_blank} +[JimmyStones' Generic Pause Module](https://github.com/JimmyStones/Pause_MiSTer){target=_blank} +[JimmyStones' Generic HiScores Module](https://github.com/JimmyStones/Hiscores_MiSTer){target=_blank} +[Compiling the Linux Kernel](https://github.com/MiSTer-devel/Main_MiSTer/wiki/Compiling-the-Linux-kernel-for-MiSTer){target=_blank} +[Compiling the bootloader](https://github.com/MiSTer-devel/Main_MiSTer/wiki/Compiling-the-boot-loader-for-MiSTer){target=_blank} +[Compiling Main_MiSTer - Arm Cross Compiling](https://github.com/MiSTer-devel/Main_MiSTer/wiki/ARM-cross-compiling){target=_blank} +[USB Blaster for Debugging](https://github.com/MiSTer-devel/Main_MiSTer/wiki/USB-Blaster-(debugging)){target=_blank} + +## Quartus Lite 17.0.2 Download Links +[Quartus Lite 17.0.2 for Windows](https://download.altera.com/akdlm/software/acdsinst/17.0std.2/602/ib_tar/Quartus-lite-17.0.2.602-windows.tar){target=_blank} +[Quartus Lite 17.0.2 for Linux](https://download.altera.com/akdlm/software/acdsinst/17.0std.2/602/ib_tar/Quartus-lite-17.0.2.602-linux.tar){target=_blank} +[Quartus 17.0 Help](https://www.intel.com/content/www/us/en/programmable/quartushelp/17.0/index.htm#quartus/gl_quartus_welcome.htm){target=_blank} + +## DE10-Nano Resources +[DE10-Nano Rev. B2/C Manual](https://www.terasic.com.tw/cgi-bin/page/archive_download.pl?Language=English&No=1046&FID=f1f656bb5f040121c36f2f93f6b107ff){target=_blank} +[DE10-Nano Schematic](https://www.terasic.com.tw/cgi-bin/page/archive_download.pl?Language=English&No=1046&FID=5d856258e00159cd47d7fe3ca35c1f3a){target=_blank} + +## General Development Resources +[Various Licenses and Comments about Them](https://www.gnu.org/licenses/license-list.html){target=_blank} diff --git a/docs/developer/mra.md b/docs/developer/mra.md new file mode 100644 index 00000000..a20805f7 --- /dev/null +++ b/docs/developer/mra.md @@ -0,0 +1,161 @@ +--- +hide: + - toc +--- + +This page explains most of the intricacies of the way MiSTer handles ROMs for Arcade systems. + +## MRA Format + +Because some arcade boards can change games by just putting in new roms, it made sense to move the RBF files out of sight from the menu list, and browse the MRA files instead. These MRA files specify which RBF file to use, and which mame rom zip files to create on the fly into a rom to pass to the arcade core. They will create the old a.pacman.rom style rom on the fly from mame roms, either merged or non-merged. + +### Here is an example of where the files might go: +```bash +/_Arcade/.mra +/_Arcade/cores/.rbf +/_Arcade/mame/.zip +/_Arcade/hbmame/.zip +``` +There are other locations for these files based on search paths. + +### MRA Format +```xml + + Donkey Kong (US set 1) + 201911270000 + 0216 + dkong + 1981 + Nintendo of America + Maze / Monkeys + Platform + Platform / Mario Bros. + DonkeyKong + + + + + + + + + + + + 0A + + + +ROM structure +00000 - 0BFFF 48k CPU1 +0C000 - 0FFFF 16k CPU2 +10000 - 13FFF 16k GFX1 +14000 - 1BFFF 32k GFX2 + + + + + + + + + + + + + + + + + + + + + + + +FE 04 38 02 3E 04 47 A7 17 A7 17 A7 17 80 80 C6 +28 + + + + + + 00 + +80 80 80 80 80 80 7F 7F 7F 7F 7F 7F 7F 80 80 80 + + + + + + + +``` + +When creating a core you can pass additional data in using ioctl_index > 0. + +```verilog +// Retrieve Title No. +always @(posedge clk_sys) begin + if (ioctl_wr & (ioctl_index==1)) tno <= ioctl_dout[3:0]; +end + +``` + +### Explanation for XML elements and attributes +* **name**: As an element this indicates how the rom should be called. The value should be taken from MAME. As an attribute this indicates an external rom file (or part thereof) that should be loaded by MiSTer. +* **mratimestamp**: This indicates the date on which the *.mra file was created (useful for other users to determine if there is a newer version of the *.mra file available to which they should upgrade). The date format is yyyymmdd. +* **mameversion**: This indicates on which version of a MAME romset the *.mra file is based (which version was used for testing). The dot in MAME's version numbering is omitted. +* **setname**: This indicates the name of the romset used as given by MAME. It is used to overwrite the core ID specified in the *.rbf file so that individual settings can be saved on a per romset basis. +* **year**: This indicates the year the game was released. The format is YYYY and the value should be taken from MAME. +* **manufacturer**: This indicates the manufacturer of the game. The value should be taken from MAME. +* **rbf**: This indicates the filename (sans path and extension) of the core that should be used to run the game. +* **buttons**: This indicates the default button mapping for the game. As the name implies, it only implies to buttons, not to directional controls. The **names** attribute specifies how the buttons are called in the MiSTer OSD while the **default** attribute specifies how the buttons are mapped to the virtual [MiSTer gamepad](../setup/controller.md). +* **switches**: This is to define the dip switches present on the arcade board. As this is a bit more complex, there is a [specific section](#Dip-Switches) for it below. +* **nvram**: This tells MiSTer to save the NVRAM data on Save Settings in the OSD. If an NVRAM was saved, it will be sent to the core as well +* **romstruct**: This is to give information about the rom structure, how the rom memory is mapped. Information contained herein is intended as a comment for other developers and not actually used by MiSTer. +* **remark**: This element is intended for general remarks. Information contained herein is intended as a comment for other developers and not actually used by MiSTer. +* **rom**: Part, patch and interleave elements must have a rom element as a parent element. An **index** attribute with a value of 1 is used to pass information to multigame cores, which machine configuration to use. For passing actual rom data you need an index value of 0. The **md5** attribute is used to specify the md5 checksum. The md5 checksum is calculated and checked by MiSTer after the whole rom is created according to the given *.mra file. You can use the Linux console to find out the checksum calculated by MiSTer when it starts the core (the command line to do so is '/media/fat/MiSTer rbffilename mrafilename'). Roms whose checksum differ from the one specified in the *.mra file won't load. Specifying the md5 checksum as “none” will disable this check. +* **part**: The part element is only allowed inside a rom element. It is used for specifying a part of the rom. The content of a part can either be embedded as a hex value into the *.mra file itself (if copyright law allows) or there can be a reference to an external file via the name attribute. If the external file is in a different zip file than the parent rom element, the filename of the zip file must be specified via the **zip** attribute. + * The **crc** attribute specifies the CRC32 checksum of the respective part (format: eight hex digits). If a crc value is specified, MiSTer will try to select the appropriate file by crc (and only revert to the filename specified by the attribute name, if the crc value does not match). This increases compatibility of the *.mra file with different MAME versions of the romset. As crc values are only relevant for external files, a crc value should only be given to a part element when there is a reference to an external file. + * The **repeat** attribute only applies to embedded parts and indicates for how long (not how many times) the sequence should be repeated. By default decimal numbers are assumed. Hex numbers must be preceded with "0x". + * Inside the rom element, the **offset** and **length** attributes only apply to external files. To use the offset attribute for internal data, the patch element must be used. Offset indicates the location inside the file from where MiSTer should start reading and length indicates the length of the sequence that MiSTer should be reading. By default decimal numbers are assumed. Hex numbers must be preceded with "0x". + * The **map** attribute specifies to only read certain parts of the corresponding part element. For example a value of "0001" (binary) means to read only every fourth byte while a value of "1010" (binary) means to read only every first and third byte. To byteswap a part you need to set a map attribute value of 21 (decimal) and enclose the respective part element in an interleave tag. +* **patch**: The patch element is only allowed inside a rom element. It is applied after the whole rom is created from its parts and overwrites the content of the rom with the content of the patch element, starting from the specified offset and for the length of the patch element's content. +* **interleave**: The interleave element is only allowed inside a rom element and can only be used as parent element to one or more part elements. Together with the mandatory **output** attribute the interleave element can be used to specify that the children part elements should be read in a certain way. For example an output-value of "32" (decimal) indicates that the children part elements ROM data should be treated as 32 bit. + +### Dip Switches + +Dip switch support in the latest version of MRA is used instead of the status bits. The DIP config str is listed in the core, and the core is responsible for reading the up to 64bits of dip data that is sent via ioctl_index 254. + + +```verilog +reg [7:0] sw[8]; +always @(posedge clk_sys) if (ioctl_wr && (ioctl_index==254) && !ioctl_addr[24:3]) sw[ioctl_addr[2:0]] <= ioctl_dout; +``` + +Switches is the dip switch setting. The **default** are the default bytes. These are used so you can default the arcade into the proper factory settings. This is useful when the factory settings aren't all OFF/OFF/OFF. Note that in the **default** hexadecimal string, the leftmost byte refers to DIP bits 7:0, the next byte to 15:8 and so on. The most significant byte thus occupies the rightmost part of the string. + +```xml + +``` + +The value C9 will apply to DIP bits 23:16. + +The dip tag let's you put in a dip switch entry. The bit number (starting at 0) is based on the way the core was written. Often MAME source code can be used to understand the bits. The numbering will depend on the rom used, the arcade core, and how things are laid out. + +* **bits**: bit number to fill out sent to the core in ioctl_data +* **name**: title for the OSD +* **ids**: title for each option in the OSD +* **values**: if you want the values to be different than 0,1,2,3 you can reorder them + +```xml + +``` diff --git a/docs/developer/principles.md b/docs/developer/principles.md new file mode 100644 index 00000000..f1d5fda0 --- /dev/null +++ b/docs/developer/principles.md @@ -0,0 +1,174 @@ +--- +hide: + - toc +--- + +Here's some tips and guidelines when contributing to the MiSTer project. + +## Indent with tabs, not spaces + +This may be a controversial subject to some, however there is good reason to indent with tabs instead of spaces in this instance. The project is uploaded to github and spaces are not handled that well by github in terms of diff compares, git blame, formatting, etc... Tabs are more compatible and will be easier for everyone to work with. + +## Comment your code when appropriate + +It may take some extra time, but it saves everyone, including yourself, time in the long run. Make sure to be relatively thorough in commenting your code. For example, a good example of commented code from the Atari7800 core in [TIA.sv](https://github.com/MiSTer-devel/Atari7800_MiSTer/blob/cfcb2603d3f718268b5de8b7742798dd5fdbc605/rtl/TIA.sv#L786){target=_blank} starting at line 786: + +```sv +module playfield +( + input clk, // Master clock + input reset, // System reset + input logic clkp, // Pixel Clock + input clock_t hclk, // Horizontal clock phase 2 + input reflect, // Control playfield, 1 makes right half mirror image + input cnt, // center signal, high means right half + input rhb, // Reset HBlank signal + input [19:0] pfc, // Combined playfield registers + output logic pf // Playfield graphics +); +``` + +When instantiating this module, this dev added a comment to the end of all of her Inputs and Outputs. One shouldn't assume everyone else knows that `hclk` is `Horizontal clock phase 2` even if the name makes sense to yourself. Other good examples of good comments are separating sections of assignments or port instantiations by category, or explaining the "Why" behind a particularly unintuitive section of code. + +However there is such a thing as commenting your code **too** much. This should also be avoided. Here is an example: + +```sv +// The 16-bit Color Look Up Table +wire [7:0] color_lut[16] = '{ + 8'd0, 8'd27, 8'd49, 8'd71, + 8'd87, 8'd103, 8'd119, 8'd130, + 8'd146, 8'd157, 8'd174, 8'd190, + 8'd206, 8'd228, 8'd255, 8'd255 + +wire TRANSP_DETECT; // Transparency Detection +}; +``` + +It's obvious that this is a color look up table because the wire is named `color_lut` so that doesn't need to be described. It's obvious that `TRANSP_DETECT` is for transparency detection. + +For an extreme and deliberately funny example: + +```sv +////////////////////////////////// +/// ~~~~~~~~~~~~~~~~~~~~~~~~~~ /// +/// REGION PRIORITY HANDLING /// +/// ~~~~~~~~~~~~~~~~~~~~~~~~~~ /// +////////////////////////////////// +case(status[28:27]) // Status Bits 27 through 28 +// Region priority is in CONF_STR section at line 256 of this file +// If line 256 is no longer valid then here is a reference to what it says: +// "D2ORS,Priority,US>EU>JP,EU>US>JP,US>JP>EU,JP>US>EU;", +// O = Option, R and S are the status bits. +// 2 status bits means there are 4 combinations of options +// Case statements for this begin with 0 and end in 3 +// Since there were two switches and 4 options as explained above you can treat 0-3 as 1-4 if you'd like +// First Case Statement (0 is actually the first one) + 0: if(hdr_u) region_req <= 1; // NTSC-U Region + else if(hdr_e) region_req <= 2; // PAL Region + else if(hdr_j) region_req <= 0; // NTSC-J Region + else region_req <= 1; // Set to NTSC-U if there is no region in the header +// Second Case Statement (1 is actually the second one) + 1: if(hdr_e) region_req <= 2; // PAL Region + else if(hdr_u) region_req <= 1; // NTSC-U Region + else if(hdr_j) region_req <= 0; // NTSC-J Region + else region_req <= 2; // Set to PAL if there is no region in the header +// Third Case Statement (2 is actually the third one) + 2: if(hdr_u) region_req <= 1; // NTSC-U Region + else if(hdr_j) region_req <= 0; // NTSC-J Region + else if(hdr_e) region_req <= 2; // PAL Region + else region_req <= 1; // Set to NTSC-U if there is region in the header +// Fourth Case Statement (3 is actually the fourth one) + 3: if(hdr_j) region_req <= 0; // NTSC-J Region + else if(hdr_u) region_req <= 1; // NTSC-U Region + else if(hdr_e) region_req <= 2; // PAL Region + else region_req <= 0; // Set to NTSC-U if there is region in the header +endcase // End of the case statement +// Okay I can put things that aren't in the case statement down here +////////////////////////////////////////////// +/// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ /// +/// END REGION OF REGION PRIORITY HANDLING /// +/// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ /// +////////////////////////////////////////////// +``` + +Please don't do things like this. + +## Align ends, assignments, and proper indentation + +Try to keep similar elements in our code aligned for readability purposes, for example, in the [EEPROM_24C0x.sv](https://github.com/MiSTer-devel/NES_MiSTer/blob/8dddb6cc01a2a2854a444838e0cfe5a17338060f/rtl/EEPROM_24C0x.sv){target=_blank} file from NES_MiSTer, this: + +```sv +// savestate +assign SS_MAP1_BACK[ 2: 0] = (state == STATE_STANDBY) ? 3'd0 : + (state == STATE_TEST) ? 3'd1 : + (state == STATE_ADDRESS) ? 3'd2 : + (state == STATE_WRITE) ? 3'd3 : + 3'd4; +``` + +...is a lot easier to read than this: + +```sv +assign SS_MAP1_BACK[ 2: 0] = (state == STATE_STANDBY) ? 3'd0 : (state == STATE_TEST) ? 3'd1 : (state == STATE_ADDRESS) ? 3'd2 : (state == STATE_WRITE) ? 3'd3 : 3'd4; +``` + +Sure, they both do the same thing, but it was much easier to parse what each thing did quickly. SystemVerilog is not a strongly typed language with regards to indentations, so you won't get compilation errors if you fail to indent your ends accurately. But we should indent them appropriately anyways. + +Another example: + +```sv +always @(posedge clk) begin + if (rst) + q <=0; + else + if (d) + q <= ~q; + else + q <= q; +end +``` + +is much easier to read than: + +```sv +always @(posedge clk) begin +if (rst) +q <=0; +else +if (d) +q <= ~q; +else +q <= q; +end +``` + +Both will succesfully compile and be functionally identical, but it takes a little longer for our mind to parse on first glance. Aligning comments at the end of a line is also helpful in improving readability as shown in the `playfield` module example near the top of this page. + +## Naming things to be easily understood + +In [EEPROM_STM95](https://github.com/MiSTer-devel/Genesis_MiSTer/blob/b15cceff237ebd6cb269119d6ec6f3b1dcbb0a8e/rtl/EEPROM_STM95.sv#L13){target=_blank} in the Genesis core, this module's port instantiation uses `_n` to signify that the signal is "active low": + +```sv +module STM95XXX +( + //... + input hold_n, // Hold (active low) + input cs_n, // Chip Select (active low) + input wp_n, // Write Protect (active low) + //... +); +``` + +It's also commented, but now you know after reading this that anytime a signal with `_n` is used, that is an active low signal, it doesn't need to be described as active low in a comment each time it is used from then on. + +## If you run out of DSP or Logic space accidentally + +If you run out of space in compilation, you might be accidentally implying your code to be put into DSP, which is very limited. You can specify that the compiler use logic instead by using the [multstyle](https://www.intel.com/content/www/us/en/programmable/quartushelp/17.0/index.htm#hdl/vlog/vlog_file_dir_multstyle.htm){target=_blank}: + +```sv +(* multstyle = "logic" *) module myModule ( + input clk +) +``` + +This will force this module into logic space instead of it ever using DSP or block ram. Also you can force a module into DSP the same way with `(* multstyle = "dsp" *)`. The `multstyle` attribute can be used for Module declarations, variable declarations, and binary expressions. diff --git a/docs/editing.md b/docs/editing.md new file mode 100644 index 00000000..5ca1f580 --- /dev/null +++ b/docs/editing.md @@ -0,0 +1,42 @@ +--- +hide: + - toc +--- + +Here's a quick guide to show you how to edit this documentation site. It's very similar to editing a wiki page, but requires a couple extra steps. All edits are approved by the administrators of the MkDocs_MiSTer repository on GitHub for quality control purposes. + +## How to edit/contribute to pages on this documentation site + +First, you will need a github account: + +[Signup to GitHub](https://github.com/signup){target=_blank} + +Next you go to the page you want to edit and click on the pen icon in the top right for that page: + +![Edit this documentation page button](img/contrib1.png) + +Then you need to fork the repository for this documentation. A repository is just what coders call the place where they store all the code for their project. A fork is just a personal copy of that repository where you can make your own changes to it. So let's click "Fork this Repository": + +![Fork the repository for this documentation page](img/contrib2.png) + +Now make your changes using the text editor. The MkDocs_MiSTer site uses the [Markdown syntax](https://www.markdownguide.org/cheat-sheet/){target=_blank}, so make sure to follow those guidelines. The editor comes with a Preview Tab so you can see how your work may appear. Certain MkDocs specific tags or formatting (e.g. `{target=_blank}` which makes your browser open a link in a new tab): + +![Use the markdown editor on GitHub to make your changes](img/contrib3.png) + +Write in a short description of your changes and propose the changes that describes why you made the changes: + +![Propose the changes to the documentation page](img/contrib4.png) + +The next step is to create a pull request. Pull requests are a way of asking the repository owner to accept the changes you've made into their repository. Double check your work to make sure it is what you wanted: + +![Check your work and click "Create pull request"](img/contrib5.png) + +The form to create a pull request will appear. This is your last chance to double-check your work before creating the pull request to ask the owner to "merge" your changes into the main repository. Merging these changes will update the site momentarily, so make sure the changes you made are correct: + +![Last chance to check your work, and then click "Create pull request"](img/contrib6.png) + +In this case, the user birdybrain submitted a very goofy change, and as such his pull request was denied (and closed). This upset birdybrain quite a bit and he was disrespectful in his reply. Be respectful and understanding and try to work with the owners of the repository. Don't be like birdybrain here: + +![Be respectful and mindful of the goal of the documentation site](img/contrib7.png) + +Hopefully that helps you learn how to edit the documentation on this site. If you completed this and edited a page, congratulations! You now should know how to use GitHub, fork a repository, commit changes to the source code, and create a pull request. \ No newline at end of file diff --git a/docs/img/contrib1.png b/docs/img/contrib1.png new file mode 100644 index 00000000..86ad7b18 Binary files /dev/null and b/docs/img/contrib1.png differ diff --git a/docs/img/contrib2.png b/docs/img/contrib2.png new file mode 100644 index 00000000..7e82c127 Binary files /dev/null and b/docs/img/contrib2.png differ diff --git a/docs/img/contrib3.png b/docs/img/contrib3.png new file mode 100644 index 00000000..d4cb5d8b Binary files /dev/null and b/docs/img/contrib3.png differ diff --git a/docs/img/contrib4.png b/docs/img/contrib4.png new file mode 100644 index 00000000..7522db3b Binary files /dev/null and b/docs/img/contrib4.png differ diff --git a/docs/img/contrib5.png b/docs/img/contrib5.png new file mode 100644 index 00000000..3e7c11e9 Binary files /dev/null and b/docs/img/contrib5.png differ diff --git a/docs/img/contrib6.png b/docs/img/contrib6.png new file mode 100644 index 00000000..cd20f0bf Binary files /dev/null and b/docs/img/contrib6.png differ diff --git a/docs/img/contrib7.png b/docs/img/contrib7.png new file mode 100644 index 00000000..da1faaac Binary files /dev/null and b/docs/img/contrib7.png differ diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..d8127abb --- /dev/null +++ b/docs/index.md @@ -0,0 +1,16 @@ +--- +hide: + - toc +--- + +![MiSTer FPGA Logo](assets/logo_small.png) + +## What is MiSTer FPGA? + +**MiSTer** is an open source project that aims to recreate various classic computers, game consoles, and arcade machines using modern hardware. It allows software and game images to run as they would on original hardware, using peripherals such as mice, keyboards, joysticks and other game controllers. + +MiSTer utilizes a readily available FPGA board called the [DE10-Nano](http://de10-nano.terasic.com){target=_blank}, which connects to your TV or monitor via HDMI video out. It can also be expanded with various [add-on boards](https://github.com/MiSTer-devel/Main_MiSTer/wiki/Addons-Overview){target=_blank}, such as a 7-port USB hub, 128MB SDRAM module, and either a Digital I/O or Analog I/O board. + +The MiSTer project is currently under active development with new cores, features, and bug-fixes appearing on a regular basis. + +Check the navigation sidebar to the left for documentation on how to use your MiSTer FPGA. diff --git a/docs/javascripts/extra.js b/docs/javascripts/extra.js new file mode 100644 index 00000000..e69de29b diff --git a/docs/setup/controller.md b/docs/setup/controller.md new file mode 100644 index 00000000..2e93354a --- /dev/null +++ b/docs/setup/controller.md @@ -0,0 +1,35 @@ +--- +hide: + - toc +--- + +Now we should define some gamepad inputs on our MiSTer. This is pretty easy to do. You should use a keyboard and your gamepad/controller for this step. For each different kind of controller you have, you should do this step, and the MiSTer will store a configuration based on that device's unique ID. + +## Defining your Gamepad's buttons +Go to the second menu in the On Screen Display where you went to for to run the Downloader or WiFi scripts. There is another option here, "Define joystick buttons". Select this option to configure your buttons on your gamepad: + +![Define your gamepad!](img/define-joystick.png) + +It will guide you through the process of detecting your general controller type by asking you to press a few d-pad buttons and maybe the analog sticks. + +Then it will ask you to assign some buttons: + +* Four face buttons and two shoulder buttons +* Start and Select +* OSD button or 2-button combo (to use instead of F12 on the keyboard) +* A few extra buttons for advanced functions + +Skip any buttons you don't want to assign (there may be a lot of them) with the spacebar. If you accidentally assign the wrong button, don't worry, just define it all over again from the start. + +If you press enter to "Finish" too early, you might miss the Analog Joystick configuration step which is important if you have analog joysticks. + +Here is a picture to give you an idea of what the buttons it is asking you to press may represent: + +![MiSTer Controller Setup](img/controller-layout.png) + +The L on the bottom left is referring to an analog joystick. Your controller may or may not have this. If it does, the step to define the analogy joystick's input is at the end, so your joystick will not work unless you go through the entire list of inputs to define. + +Another important button is the OSD button. Many modern controllers have a "Home" button, it's probably best to assign this to the OSD/Menu. If you do not assign anything to home, the only way to access the menu will be to use the F12 key on a keyboard. + +### Define Gamepad Inputs/Buttons Example Video +![type:video](videos/define-gamepad.mp4) diff --git a/docs/setup/games.md b/docs/setup/games.md new file mode 100644 index 00000000..719fe976 --- /dev/null +++ b/docs/setup/games.md @@ -0,0 +1,40 @@ +--- +hide: + - toc +--- + +To play games on the MiSTer you will need to transfer them to your MicroSD. There are other ways to load games, like over a NAS or using USB drive, but for now we're going to stick to the most basic easy method. If you'd like more information on these other methods you can head to the [Advanced Networking Page](../advanced/network.md) of this site, to find out more. + +## Games folder description +The `/games/` folder is where ROMs are stored. `/games/NES` is where you would place NES ROMs, for instance. Each MiSTer core looks to a specific folder for these ROMs so it is best to put them in the right place. + +## Transfer ROMs over the Network with Samba/SMB +The MiSTer comes setup with a Samba server already, it just needs to be activated. This means you can connect to it like any other shared folder on the network. It's pretty easy. + +First we need to enable the Samba service: + +1. Enter the terminal/command line of the MiSTer by press `F9` on your keyboard and type `root` for the username, press enter, and type `1` for the password and press enter. +2. Rename `/media/fat/linux/_samba.sh` to `/media/fat/linux/samba.sh` in the terminal/console on the MiSTer by running the following command: +``` +mv /media/fat/linux/_samba.sh /media/fat/linux/samba.sh +``` +3. Reboot the MiSTer +4. If you are using Windows, all you need to do is type `\\MiSTer\sdcard\` in the address bar at the top of the File Explorer and press enter. You can do the same in Linux or on MacOS depending on how you access network shares on those systems the same way. + +![MiSTer FPGA Samba Server File Explorer](img/samba.png) + +In this case I'm going to transfer some ROMs to the `/games/NES/` folder so I can use them with the NES core. + +![ROM Transfer to MiSTer FPGA folder from Windows](img/rom-transferred.png) + +## Transfer ROMs to the MicroSD directly +You can also turn off the MiSTer, remove the MicroSD and plug it into your computer to transfer roms. It will have an exFAT formatted partition named "MiSTer" that most operating systems can work with. + +After this is done you can proceed to the next step since we are going to [Play a Game](play.md). + +## File Formats +CD images for any cores that use CD's must either be in CUE/BIN or CHD. CD Images can't be placed in zip folders/archives. + +VHD (virtual hard drive) files are the same, they must not be zipped. + +All other ROMs can be placed in zip folders/archives and accessed. The core will tell you which file extensions are accepted. If you have an issue with a ROM loading, the readme for that core that is available on GitHub or in the `/games/$CORE/` folder should tell you what kinds of files work with that core. diff --git a/docs/setup/img/balena-1.png b/docs/setup/img/balena-1.png new file mode 100644 index 00000000..c130b01d Binary files /dev/null and b/docs/setup/img/balena-1.png differ diff --git a/docs/setup/img/balena-2.png b/docs/setup/img/balena-2.png new file mode 100644 index 00000000..27aafdb1 Binary files /dev/null and b/docs/setup/img/balena-2.png differ diff --git a/docs/setup/img/balena-3.png b/docs/setup/img/balena-3.png new file mode 100644 index 00000000..adc06dae Binary files /dev/null and b/docs/setup/img/balena-3.png differ diff --git a/docs/setup/img/balena-4.png b/docs/setup/img/balena-4.png new file mode 100644 index 00000000..543ecc0d Binary files /dev/null and b/docs/setup/img/balena-4.png differ diff --git a/docs/setup/img/balena-5.png b/docs/setup/img/balena-5.png new file mode 100644 index 00000000..34b1b11a Binary files /dev/null and b/docs/setup/img/balena-5.png differ diff --git a/docs/setup/img/controller-layout.png b/docs/setup/img/controller-layout.png new file mode 100644 index 00000000..6f5c927f Binary files /dev/null and b/docs/setup/img/controller-layout.png differ diff --git a/docs/setup/img/de10-nano-microsd.png b/docs/setup/img/de10-nano-microsd.png new file mode 100644 index 00000000..c01060bb Binary files /dev/null and b/docs/setup/img/de10-nano-microsd.png differ diff --git a/docs/setup/img/define-joystick.png b/docs/setup/img/define-joystick.png new file mode 100644 index 00000000..ebca946b Binary files /dev/null and b/docs/setup/img/define-joystick.png differ diff --git a/docs/setup/img/dl-mr-fusion.png b/docs/setup/img/dl-mr-fusion.png new file mode 100644 index 00000000..ee834ad3 Binary files /dev/null and b/docs/setup/img/dl-mr-fusion.png differ diff --git a/docs/setup/img/rom-transferred.png b/docs/setup/img/rom-transferred.png new file mode 100644 index 00000000..b6fe6340 Binary files /dev/null and b/docs/setup/img/rom-transferred.png differ diff --git a/docs/setup/img/run-mr-fusion.png b/docs/setup/img/run-mr-fusion.png new file mode 100644 index 00000000..fceaeeda Binary files /dev/null and b/docs/setup/img/run-mr-fusion.png differ diff --git a/docs/setup/img/samba.png b/docs/setup/img/samba.png new file mode 100644 index 00000000..795968dc Binary files /dev/null and b/docs/setup/img/samba.png differ diff --git a/docs/setup/img/static-menu.png b/docs/setup/img/static-menu.png new file mode 100644 index 00000000..7f25897e Binary files /dev/null and b/docs/setup/img/static-menu.png differ diff --git a/docs/setup/play.md b/docs/setup/play.md new file mode 100644 index 00000000..ff98aceb --- /dev/null +++ b/docs/setup/play.md @@ -0,0 +1,16 @@ +--- +hide: + - toc +--- + +Next all we need to do is load the core for the system we want to play. In our case it is the NES core. Just select Console then NES and hit enter or the button you assigned "A" on the controller earlier. The core will load. You may need to press the Menu button you assigned earlier or F12 on the keyboard to bring the menu up. Once your menu is up, select Load ROM and load your game. + +Once the game loads, you will want to turn on Autosave if your game saves. Basically, the MiSTer has to be told when to save your game. Let's say you save your progress in Final Fantasy for the NES, each time you do this, you need to open the On Screen Display to tell it to save. The autosave setting makes it so all you have to do is open the menu, so it's a good idea to turn it on so you don't forget. + +Anytime you change a core setting in the menu that you want to keep, you need to save that setting. So since we always want autosave to be on, after turning it on we just switch to the secondary OSD menu (by pressing right on the controller) and select "Save Settings". It's that easy. + +Here's a short video showing you how to load a core, load the game, and turn on autosave. + +![type:video](videos/load-autosave.mp4) + +That's it! It wasn't so bad, you made it through the tutorial. Please be sure to check out all the other sections of this documentation, there are some valuable options to configure, tips and tricks to learn, that will make your experience much better. diff --git a/docs/setup/requirements.md b/docs/setup/requirements.md new file mode 100644 index 00000000..0fdd661c --- /dev/null +++ b/docs/setup/requirements.md @@ -0,0 +1,40 @@ +--- +hide: + - toc +--- + +There are a few things you will need in order to setup your MiSTer: + +* Terasic DE10-Nano +* MiSTer SDRAM Add-On Board (Optional but many cores require it) +* Cooling for the FPGA (Highly recommended) +* MicroSD card (minimum 4GB) and MicroSD Card Reader +* USB OTG Adapter or MiSTer USB Hub Add-On Board (no USB devices will work without this) +* USB Keyboard +* Internet connection +* HDMI Monitor/TV and HDMI Cable + +## Where to buy +**DE10-Nano:** + +* [Terasic](http://de10-nano.terasic.com){target=_blank} +* [Digikey](https://www.digikey.com/en/products/detail/terasic-inc/P0496/6817231){target=_blank} +* [Mouser](https://www.mouser.com/ProductDetail/Terasic-Technologies/P0496?qs=sGAEpiMZZMug%252BNZZT2EIMybLXjFfYtXHeZj9cpOi%2FsY%3D){target=_blank} + +**SDRAM:** + +The MiSTer SDRAM add-on board is required by many cores, like the SNES, NES, Playstation, and Game Boy cores. There are multiple sellers out there which sell these, and you can also assemble it yourself if you are skilled at soldering. + +**USB OTG Adapter/Hub:** + +Preferably, the MiSTer USB Hub Add-on board which you can assemble yourself if you are good at soldering, or you can buy from the various shops that sell them. + +At a minimum, the [MakerSpot Micro USB OTG Hub](https://www.amazon.com/MakerSpot-Accessories-Charging-Extension-Raspberry/dp/B01JL837X8){target=_blank} works very well for the MiSTer, if you are looking for a very cheap option. + +**Cooling:** + +The processor on the DE10-Nano is 21.5mm x 21.5mm so a heatsink that is around this size is suitable. If using one larger than these dimensions, please make sure to use care to not let the heatsink touch other electronic components outside the processor. + +There is no mounting mechanism for the heatsink, you will need to use an "adhesive thermal pad". 3M makes some good ones, and the heatsinks you can buy in this size usually come with these kinds of thermal pads already. + +Do not apply a lot of pressure and do not touch the components directly with your fingers, as static shock can damage them. diff --git a/docs/setup/software.md b/docs/setup/software.md new file mode 100644 index 00000000..438a0228 --- /dev/null +++ b/docs/setup/software.md @@ -0,0 +1,53 @@ +--- +hide: + - toc +--- + +First thing to do is to install the software onto your MicroSD card. + +## Flash Mr. Fusion to your MicroSD +Mr. Fusion provides a compact image that you can download and flash onto an SD card of any size with a tool like [balenaEtcher](https://www.balena.io/etcher/){target=_blank}, [Win32 Disk Imager](https://sourceforge.net/projects/win32diskimager/){target=_blank}, [Apple Pi Baker](https://www.tweaking4all.com/software/macosx-software/applepi-baker-v2/){target=_blank}, or even [dd](https://en.wikipedia.org/wiki/Dd_%28Unix%29){target=_blank}. + +We're going to use balenaEtcher for this guide. We install balenaEtcher by [downloading the latest release for our computer](https://www.balena.io/etcher/){target=_blank} and installing it. + +Next we're going to [download the latest release of Mr. Fusion](https://github.com/MiSTer-devel/mr-fusion/releases){target=_blank}: + +[![Download Mr. Fusion](img/dl-mr-fusion.png)](https://github.com/MiSTer-devel/mr-fusion/releases){target=_blank} + +Next, we will insert our MicroSD card into our computer and then open balenaEtcher. We will select "Flash from file" and navigate to the Mr Fusion file we downloaded a step earlier. + +![Flash from file](img/balena-1.png) + +Then we need to select our MicroSD card as the target to flash. + +![Select target MicroSD](img/balena-2.png) +![Select the right one](img/balena-3.png) + +And click "Flash!" + +![Flash that card!](img/balena-4.png) + +Wait for it to complete successfully. + +![Successful flash :)](img/balena-5.png) + +If you see "Flash complete!" and "1 Successful target" then everything worked fine. If the flash fails, try and flash it again or flash a different MicroSD card in case the one you are using is malfunctioning. + +We can now close balenaEtcher and remove our MicroSD card. + +## Boot the DE10-Nano with Mr. Fusion +Next we just need to carefully insert our MicroSD card into the DE10-Nano (**NOT the MicroSD slot on the IO board on top!**). + +![Location of DE10-Nano MicroSD slot on the bottom](img/de10-nano-microsd.png) + +Now turn on your DE10-Nano. + +We will wait up to a few minutes for the Mr. Fusion installer to complete. Be patient, or else you may have to start all over again. + +![Running Mr. Fusion](img/run-mr-fusion.png) + +When the MiSTer On Screen Display with fuzzy static behind it appears, that means you have successfully installed the MiSTer software/OS onto your MicroSD. + +![Fuzzy Static Displaying Away!](img/static-menu.png) + +Check out the next tutorials in the side bar! diff --git a/docs/setup/updater.md b/docs/setup/updater.md new file mode 100644 index 00000000..a56dfc13 --- /dev/null +++ b/docs/setup/updater.md @@ -0,0 +1,13 @@ +--- +hide: + - toc +--- + +We need to update the MiSTer the first time you get it setup. This is because the MiSTer currently only has a script to update it, no cores, no arcade files, and it's system files may be outdated. If you don't have a wired internet connection to your MiSTer, please remove your microSD and place the WiFi script into the `scripts` folder, and then follow the instructions in the [WiFi tutorial](../basics/wifi.md#setup-wifi-with-a-script). + +## Running Downloader.sh +Now that your MiSTer is connected to either a wired internet connection or a WiFi connection, you should run an update. This may take awhile the first time, but each time you run the updater after that it will take a lot less time. It's important to update your MiSTer regularly as the framework, cores, and software is updated frequently with bug fixes, features, and new cores. + +It's very easy to run Downloader.sh, just navigate to the scripts selection in the On Screen Display (osd) in the Menu core, select it, and go to the `distribution` script and select it. See video below for an example of the downloader script running: + +![type:video](videos/downloader.mp4) diff --git a/docs/setup/videos/define-gamepad.mp4 b/docs/setup/videos/define-gamepad.mp4 new file mode 100644 index 00000000..7315adee Binary files /dev/null and b/docs/setup/videos/define-gamepad.mp4 differ diff --git a/docs/setup/videos/downloader.mp4 b/docs/setup/videos/downloader.mp4 new file mode 100644 index 00000000..5c2f869d Binary files /dev/null and b/docs/setup/videos/downloader.mp4 differ diff --git a/docs/setup/videos/load-autosave.mp4 b/docs/setup/videos/load-autosave.mp4 new file mode 100644 index 00000000..15aaf559 Binary files /dev/null and b/docs/setup/videos/load-autosave.mp4 differ diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 00000000..9c6ee983 --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,40 @@ +* { + --md-default-fg-color: #f8f8f2de; + --md-default-fg-color--light: #f8f8f28a; + --md-default-fg-color--lighter: #f8f8f252; + --md-default-fg-color--lightest: #f8f8f212; + --md-default-bg-color: #44475a; + --md-default-bg-color--light: #44475a; + --md-default-bg-color--lighter: #44475a4d; + --md-default-bg-color--lightest: #44475a1f; + + --md-primary-fg-color: #514689; + --md-primary-fg-color--light: #5146898a; + --md-primary-fg-color--lighter: #51468952; + --md-primary-fg-color--lightest: #51468912; + + --md-typeset-a-color: #a7a4e0; + --md-accent-fg-color: #514689; + + --md-code-fg-color: #f8f8f2; + --md-code-bg-color: #282a36; + --md-code-hl-color: #f1fa8c; + --md-code-hl-number-color: #bd93f9; + --md-code-hl-special-color: #db1457; + --md-code-hl-function-color: #a846b9; + --md-code-hl-constant-color: #6e59d9; + --md-code-hl-keyword-color: #ff79c6; + --md-code-hl-string-color: #1c7d4d; + --md-code-hl-name-color: #8be9fd; + --md-code-hl-operator-color: var(--md-code-hl-keyword-color); + --md-code-hl-punctuation-color: var(--md-code-fg-color); + --md-code-hl-comment-color: #6272a4; + --md-code-hl-generic-color: #f8f8f28a; + --md-code-hl-variable-color: var(--md-code-h1-generic-color); + + --md-footer-fg-color: #ffffff; + --md-footer-fg-color--light: #ffffffe5; + --md-footer-fg-color--lighter: #ffffffc7; + --md-footer-bg-color: #514689de; + --md-footer-bg-color--dark: #51468952; +} diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..94212544 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,167 @@ +site_name: MiSTer FPGA Documentation +site_url: https://MiSTer-devel.github.io/MkDocs_MiSTer/ +site_author: Kevin Coleman +site_description: >- + MiSTer FPGA is an open project that aims to recreate various + classic computers, game consoles, and arcade machines, using + modern hardware. +copyright: Copyright © 2022 MiSTer FPGA + +repo_name: MkDocs_MiSTer +repo_url: https://github.com/MiSTer-devel/MkDocs_MiSTer/ +edit_uri: edit/main/docs/ + +theme: + palette: + # Currently only dark color scheme supported, it is modified in overrides folder + - scheme: slate + name: material + favicon: assets/favicon.ico + logo: assets/mister_kun_bw.svg + font: + text: Roboto + code: Source Code Pro + features: + # Highlight search terms when user searches for things + - search.highlight + # Offer most likely search result as a suggestion + - search.suggest + # Update url with the active anchor as highlighted in ToC + - navigation.tracking + # Expands the table of contents on the left by default + - navigation.expand + # Folder for css and page overrides + custom_dir: overrides + + +plugins: +# Explicitly call out search ahead of time, because if you use other plugins this has to be done. + - search: + # Only English for now + lang: en + # mkdocs-rss-plugin + # https://MiSTer-devel.github.io/MkDocs_MiSTer/feed_rss_updated.xml + # https://MiSTer-devel.github.io/MkDocs_MiSTer/feed_rss_created.xml + - rss: + image: assets/mister_kun_bw.svg + # Permits the use of embedded videos + - mkdocs-video + # Adds date/time stamp to page when updated according to git history. + - git-revision-date-localized + # Makes things load faster at the cost of a little extra build time + - minify: + minify_html: true + # - social: + # cards_color: + # fill: "#44475a" + # text: "#f8f8f2de" + # cards_font: Roboto + + +# Customization +extra: + # Subject to change later when incorporated into the project, potentially https://docs.misterfpga.org/ + homepage: https://MiSTer-devel.github.io/MkDocs_MiSTer/ + # Placeholder for analytics configuration, modify values and uncomment when ready + # analytics: + # provider: google + # property: !ENV GOOGLE_ANALYTICS_KEY + social: + - icon: twitter + link: https://twitter.com/MiSTerFPGABot/ + - icon: discord + link: https://discord.com/invite/misterfpga/ + - icon: github + link: https://github.com/MiSTer-devel/ + - icon: forum + link: https://misterfpga.org/ + + +nav: + # Only the logo and brief summary of what the project is about + - Home: index.md + + # Setup section is to remain very stable and simple + - First-time Setup: + - Requirements: setup/requirements.md + - Setup MicroSD Card: setup/software.md + - Running the Updater: setup/updater.md + - Define Your Gamepad: setup/controller.md + - Transferring Games: setup/games.md + - Play a Game: setup/play.md + + # Just some basics things to go over. Slightly more advanced than the setup section above + - The Basics: + - FAQ: basics/faq.md + - Hotkeys: basics/hotkey.md + - Controllers: basics/input.md + - Keyboards: basics/keyboard.md + - WiFi: basics/wifi.md + - Bluetooth: basics/bluetooth.md + - Video Configuration: basics/video.md + - CD-based ROMs: basics/cd.md + - Links: basics/links.md + + # General core information, not a full replacement for the core Readme's however + - Cores: + - What Is a Core: cores/what.md + # Just a good place to show off special features of some cores, to get people started. + - Common Core Features: + - Cheats: cores/features/cheats.md + - Core Highlights: + - SNES: cores/highlights/snes.md + - NES: cores/highlights/nes.md + - Genesis: cores/highlights/genesis.md + - TurboGrafx-16: cores/highlights/tgfx16.md + #- Atari 7800: cores/highlights/atari7800.md + - Game Boy 2 Player: cores/highlights/gb2p.md + - Console Cores: cores/console.md + - Computer Cores: cores/computer.md + - Arcade Cores: cores/arcade.md + - Core Paths: cores/paths.md + + # More advanced configuration options. Anything not basic or not simple essentials, dump here. + - Advanced Configuration: + - Troubleshooting: advanced/troubleshooting.md + - Networking: + - Setting Up SSH, FTP, and NAS: advanced/network.md + - Computer Core Networking: advanced/computer.md + - Video: + - Using Your CRT With MiSTer: advanced/crt.md + - Direct Video Adapter: advanced/directvideo.md + - Audio Filters: advanced/audio.md + - MIDI: advanced/midi.md + - Multi-Button Mapping: advanced/multibutton.md + - INI Settings: advanced/ini.md + - Lag Explained: advanced/lag.md + - Console Connection: advanced/console.md + + # Developer reference. This is going to mostly mirror what is up on Github wiki already. + - Developer Reference: + - Core Configuration String: developer/conf_str.md + - Arcade ROMS and MRA Files: developer/mra.md + - Useful Links: developer/links.md + - Tips and Guidelines: developer/principles.md + + # Fun guide that shows users how to edit the documentation site + - Editing Docs: editing.md + + +markdown_extensions: + # https://facelessuser.github.io/pymdown-extensions/extensions/highlight/ + - pymdownx.highlight: + anchor_linenums: true + # https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/ + - pymdownx.inlinehilite + # https://facelessuser.github.io/pymdown-extensions/extensions/snippets/ + - pymdownx.snippets + # https://facelessuser.github.io/pymdown-extensions/extensions/superfences/ + - pymdownx.superfences + # https://squidfunk.github.io/mkdocs-material/reference/images/ + - attr_list + +extra_css: + - stylesheets/extra.css + +extra_javascript: + - javascripts/extra.js diff --git a/overrides/.gitkeep b/overrides/.gitkeep new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/overrides/.gitkeep @@ -0,0 +1 @@ + diff --git a/overrides/.icons/discord.svg b/overrides/.icons/discord.svg new file mode 100644 index 00000000..1c351f58 --- /dev/null +++ b/overrides/.icons/discord.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/overrides/.icons/forum.svg b/overrides/.icons/forum.svg new file mode 100644 index 00000000..f3654a83 --- /dev/null +++ b/overrides/.icons/forum.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/overrides/.icons/github.svg b/overrides/.icons/github.svg new file mode 100644 index 00000000..53bd7b2d --- /dev/null +++ b/overrides/.icons/github.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/overrides/.icons/twitter.svg b/overrides/.icons/twitter.svg new file mode 100644 index 00000000..f0ed9c5f --- /dev/null +++ b/overrides/.icons/twitter.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/overrides/partials/footer.html b/overrides/partials/footer.html new file mode 100644 index 00000000..39980439 --- /dev/null +++ b/overrides/partials/footer.html @@ -0,0 +1,37 @@ + + + +